Troubleshooting Deploy Failures

When a deployment encounters an issue, JetStack AI logs detailed error information for each affected asset in the Activity detail page. This guide covers the most common errors, their causes, and how to resolve them.

General Deployment Errors

Duplicate Name

Symptom: An asset fails with an error indicating a duplicate name or that an asset with the same name already exists.

Cause: The target portal already contains an asset with the same name. While JetStack AI’s duplicate detection normally catches this and reuses the existing asset, some edge cases can trigger a conflict — particularly when two assets of the same type are created in rapid succession, or when the existing asset was created between the analysis and deploy phases.

Solution: Check the target portal for the duplicate asset. If it was created by a previous deployment attempt, you can safely re-run the deployment — duplicate detection will match the existing asset. If it is a genuinely different asset that happens to share the same name, rename one of them in either the source library or the target portal.

Mapping Not Found

Symptom: An asset deploys but generates warnings about missing mappings, or a required mapping prevents the deployment from proceeding.

Cause: A property, pipeline stage, owner, or other reference in the asset does not have a corresponding mapping configured, and no auto-match was found in the target portal.

Solution: Return to the mapping step and configure the missing mapping. If the referenced property or stage does not exist in the target portal, create it there first, then re-run the deployment. For optional mappings that show as warnings, review the affected asset in the target portal and manually update the reference.

API Rate Limit

Symptom: Multiple assets fail with rate limit errors, especially in large deployments (100+ assets).

Cause: HubSpot enforces API rate limits based on your portal’s subscription tier. Very large deployments can temporarily exceed these limits despite JetStack AI’s built-in rate limiting and retry logic.

Solution: Wait 10-15 minutes for the rate limit window to reset, then retry the failed assets from the activity detail page. For consistently large deployments, consider splitting them into smaller batches (e.g., deploy properties and pipelines first, then workflows and emails in a second pass). JetStack AI automatically retries rate-limited requests with exponential backoff, so most transient rate limit hits are handled without user intervention.

Property Type Mismatch

Symptom: A property fails to create with an error about conflicting types, or the property exists with a different type than expected.

Cause: The target portal already has a property with the same internal name but a different type. For example, a property named priority exists as a “number” in the target portal but the source asset defines it as a “single-line text” (string).

Solution: JetStack AI uses a suffix strategy to resolve type conflicts. The conflicting property is created with a _type_supr suffix appended to the internal name (e.g., priority_type_supr). References in deployed assets are updated to use the suffixed name. After deployment, review the suffixed properties in the target portal and decide whether to keep them or consolidate with the existing property manually.

Pipeline Creation Failed

Symptom: A pipeline or pipeline stage fails to create in the target portal.

Cause: Several issues can trigger this:

• Probability validation — Deal stage probability must be between 0.0 and 1.0. Values outside this range are rejected by HubSpot.
• Existing conflict — The target portal already has a pipeline with the same name but different stage configuration, and the auto-matching resolved incorrectly.
• Plan limits — The target portal’s HubSpot plan may limit the number of pipelines allowed.

Solution: Check the specific error message in the activity detail. For probability issues, verify the source stage’s probability value and correct it if necessary. For conflicts, manually align the target pipeline’s stages with what the deployment expects, or remove the conflicting pipeline. For plan limits, upgrade the target portal’s HubSpot subscription or reduce the number of pipelines being deployed.

Template Not Found

Symptom: A page or email fails to deploy with a “template not found” error.

Cause: The page or email references a template that either was not included in the deployment, failed to deploy in an earlier step, or could not be matched in the target portal.

Solution: Verify that the required template is included in your asset selection. If the template deployment failed, resolve that error first and re-deploy. If the template was supposed to match an existing template in the target portal, check that the names match exactly.

Timezone Validation Error

Symptom: A list or workflow filter fails with a timezone-related validation error.

Cause: HubSpot’s API rejects certain timezone formats. Specifically, IANA timezone identifiers (e.g., America/New_York) are rejected in favor of legacy timezone identifiers (e.g., US/Eastern) in some API endpoints. Additionally, certain relative date references are only valid with specific reference types.

Solution: JetStack AI automatically retries with a UTC fallback when timezone validation fails. If the retry also fails, check the specific filter in the source asset. The most common issue occurs with TIME_RANGED filters in lists, where the indexReference.referenceType only accepts TODAY or NOW (not MONTH or other values). Review the list filter configuration and simplify the time reference if needed.

Circular Dependency Detected

Symptom: One or more assets show a “circular dependency” status and are skipped during deployment.

Cause: Two or more assets reference each other in a way that creates a dependency cycle. For example, Workflow A enrolls contacts from List B, and List B filters on a property set by Workflow A.

Solution: Circular dependencies are gracefully skipped — the engine detects the cycle and logs it rather than entering an infinite loop. To deploy these assets, break the cycle by deploying them in two passes: deploy one asset without the circular reference first, then update it after the second asset is deployed. In most cases, workflows involved in circular dependencies can be deployed without their enrollment criteria and updated manually afterward.

Per-Asset-Type Issues

Workflows

Symptom: A workflow deploys but some filter conditions or actions are incorrect or missing.

Cause: Workflow filters undergo transformation during deployment to remap property names, values, and operators. Complex filter trees with nested AND/OR groups can occasionally have conditions that do not translate cleanly.

Solution: After deployment, open the workflow in the target portal and review each filter condition and action step. Pay particular attention to:

• Filters referencing custom properties (verify the property mapping)
• Actions that set owner values (verify owner mappings)
• Enrollment triggers using list membership (verify the list deployed correctly)

Lists

Symptom: A list fails or deploys with incorrect filter criteria.

Cause: Lists with TIME_RANGED filters are the most common source of issues. Specific problems include:

• The upperBoundEndpointBehavior field (not upperBoundEndpoint) controls whether the bound is EXCLUSIVE or INCLUSIVE
• IANA timezone formats (e.g., America/New_York) are rejected — JetStack AI remaps these to legacy formats (e.g., US/Eastern) automatically
• indexReference.referenceType only accepts TODAY or NOW in POST requests — MONTH and other values are rejected

Solution: If the automatic timezone remapping and filter transformation do not resolve the issue, create the list manually in the target portal using HubSpot’s list builder. Review the source list’s filter criteria and replicate it using the target portal’s available options.

Forms

Symptom: A form deploys but is missing fields or has an incorrect layout.

Cause: HubSpot forms have evolved across API versions (v2 and v3), and field handling differs between them. Specific issues include:

• v2/v3 field format differences — Some field properties exist only in one API version
• Field group maximum — HubSpot limits the number of fields per row to 3 in the form editor. Source forms with more fields per group may be restructured.

Solution: Review the deployed form in the target portal’s form editor. Verify all fields are present and correctly ordered. If fields are missing, check whether the corresponding properties exist in the target portal — form fields are tied to properties, and a missing property means the field cannot be created.

Emails

Symptom: A marketing email deploys but has missing content sections, broken subscription links, or incorrect A/B test configuration.

Cause: Email deployment involves several complex transformations:

• Subscription type rebuild — Subscription preferences are portal-specific and must be remapped
• A/B test state — A/B test configurations reference variant IDs that are portal-specific. Emails with active A/B tests may deploy without the test configuration.

Solution: After deployment, open the email in the target portal’s email editor. Verify subscription type settings under the “Settings” tab. If the email had an A/B test, you will need to recreate the test variants manually in the target portal.

Blog Posts

Symptom: A blog post fails to deploy or deploys with incorrect metadata.

Cause: Blog posts have two common issues:

• Parent blog required — Every blog post must belong to a blog. If the parent blog does not exist in the target portal and was not included in the deployment, the post cannot be created.
• Epoch-0 timestamps — Some blog posts imported from older portals have publish dates set to epoch 0 (January 1, 1970). HubSpot’s API may reject or mishandle these dates.

Solution: For missing parent blogs, include the blog in your deployment or create it manually in the target portal first. For timestamp issues, the post will deploy as a draft with no publish date — set the publish date manually in the target portal’s blog editor.

HubDB Tables

Symptom: A HubDB table deploys but has missing or incorrect row data.

Cause: HubDB tables with foreign key columns (columns that reference rows in other HubDB tables) require a two-phase deployment. The referenced table must be created with its rows first, then the foreign key references can be resolved.

Solution: If foreign key resolution fails, verify that both the source and target HubDB tables were included in the deployment. Re-deploy if the referenced table was created but its row IDs were not yet available when the referencing table was deployed. The second deployment attempt will find the existing tables and resolve the foreign keys.

Properties

Symptom: A property fails to create or has an unexpected configuration.

Cause: The most common property-specific issue is the currency field edge case. Properties of type “currency” require additional configuration (currency code, format) that may not transfer cleanly between portals with different default currencies.

Solution: Review the failed property in the activity detail for the specific error. For currency properties, check the target portal’s default currency settings and ensure they support the currency format used by the source property. You may need to create the property manually with the correct currency configuration.

General Recovery Steps

When multiple assets fail in a deployment:

1. Review the activity detail — Each failed asset shows its specific error message
2. Fix root causes first — If a template failed and pages depend on it, fix the template issue before retrying pages
3. Retry from the activity page — Use the retry option to re-attempt failed assets without re-running the entire deployment
4. Check skipped mappings — Review the skippedMappings log for fallback values that may need manual correction
5. Verify in the target portal — After successful deployment, spot-check a few assets in HubSpot to confirm they look and function as expected