Troubleshooting Import Failures
Most imports complete without issues, but when problems occur, this page helps you identify the cause and resolve it. Errors are grouped into general import failures, per-asset-type issues, and recovery procedures.
General Import Errors
Section titled “General Import Errors”Failed to Fetch Asset
Section titled “Failed to Fetch Asset”Symptom: An individual asset fails with a “failed to fetch” or “asset not found” error.
Possible causes:
- Portal disconnected — The OAuth connection to the source portal has expired or been revoked. Check your Client Accounts page. If the portal shows a disconnected status, reconnect it and retry.
- Asset deleted — The asset was deleted from HubSpot between when you loaded the selection list and when the import ran. Refresh the import wizard and verify the asset still exists in HubSpot.
- Insufficient permissions — The HubSpot user who authorized the OAuth connection does not have access to this specific asset. This commonly happens with workflows or emails restricted to specific teams. Re-authorize with a Super Admin account.
Dependency Import Failed
Section titled “Dependency Import Failed”Symptom: An asset you selected imported successfully, but one of its dependencies failed, causing the parent asset to be stored with an incomplete dependency set.
Cause: The dependency asset itself encountered one of the errors listed on this page (deleted, permissions, rate limit, etc.). The parent asset’s import continues, but it is flagged with a missing dependency.
Solution: Check the Activity Log to identify which specific dependency failed and why. Resolve the underlying issue for the dependency, then retry the import. If the dependency is not critical for your use case, you can proceed with deployment — JetStack AI will skip the missing reference during deployment and log a warning.
API Rate Limit Exceeded
Section titled “API Rate Limit Exceeded”Symptom: Import slows dramatically or fails with a rate limit error, typically when importing a large number of assets.
Cause: HubSpot enforces API rate limits per portal. When JetStack AI makes many API calls in quick succession (fetching assets, resolving dependencies, downloading images), it can approach or hit these limits.
Solution:
- Reduce batch size. Instead of importing 100+ assets at once, break your import into smaller batches of 20-30 assets.
- Wait and retry. HubSpot rate limits reset on a rolling window. Wait 5-10 minutes and retry the failed import.
- Check other integrations. If other tools are also making API calls to the same portal simultaneously, they compete for the same rate limit. Coordinate timing if possible.
JetStack AI includes intelligent retry logic with backoff that respects HubSpot’s rate limit headers, but extremely large imports may still encounter limits.
Asset Type Not Supported
Section titled “Asset Type Not Supported”Symptom: An asset type appears grayed out or shows a plan restriction notice in the import wizard.
Cause: Your current JetStack AI plan does not include the asset type you are trying to import. Ultimate assets (Dashboards, Reports, Snippets, Goal Templates, Lead Scores, CRM Cards, Preview Views, Playbooks) require the Ultimate plan.
Solution: Upgrade your plan at Account > Billing or contact your account manager. See Plans and Limits for a feature comparison.
Image Upload Failed
Section titled “Image Upload Failed”Symptom: An asset imports successfully but one or more images fail to cache.
Possible causes:
- Large image file — Images exceeding the size limit may fail to upload to Firebase Storage. HubSpot occasionally hosts very large uncompressed images.
- Unsupported format — While JetStack AI handles all standard web formats (JPEG, PNG, GIF, WebP, SVG), rare or corrupted image formats may fail.
- Source URL inaccessible — The image is hosted on a domain that blocks external downloads or requires authentication.
Solution: The asset itself is still imported — only the image cache is affected. During deployment, JetStack AI will attempt to fetch the image from the original URL. If it remains unavailable, you can manually upload a replacement image in the destination portal after deployment.
Timeout
Section titled “Timeout”Symptom: The import process times out before completing, typically on a single large asset.
Cause: The asset has an exceptionally large configuration (a workflow with hundreds of actions, a page with dozens of embedded modules) or an extremely deep dependency tree that takes longer to traverse than the timeout window allows.
Solution:
- Retry the import. Transient network issues can cause timeouts. A simple retry often succeeds.
- Import the asset individually. Remove it from a large batch import and import it on its own to isolate the issue.
- Check the dependency chain. If the asset has an unusually deep dependency tree, try importing some of the deeper dependencies first in a separate import, then import the top-level asset.
Permission Denied
Section titled “Permission Denied”Symptom: Import fails with a permissions or scope error.
Cause: The OAuth token for the source portal is missing required scopes. This happens when the portal was connected before JetStack AI added support for certain asset types, or when the authorizing user has restricted permissions.
Solution: Navigate to Client Accounts, disconnect the portal, and reconnect it. The new OAuth flow will request all current required scopes. Ensure the authorizing user has Super Admin access for the broadest permission set. See OAuth Scopes for a list of required scopes by asset type.
Per-Asset-Type Issues
Section titled “Per-Asset-Type Issues”Workflows
Section titled “Workflows”Issue: Complex enrollment criteria not fully captured
Some workflows use enrollment criteria that reference advanced HubSpot features (custom behavioral events, predictive lead scoring properties, or beta features). If the parser does not recognize a specific criteria type, it stores the raw criteria data and logs a warning. The workflow will still import, but the unrecognized criteria may need manual adjustment after deployment.
Issue: TIME_RANGED filters with timezone discrepancies
Lists using time-ranged date filters may encounter timezone handling differences between what HubSpot returns and what it accepts. If you see errors related to timezone formatting or endpoint behavior during import, the list data is still captured — the filter configuration may need review after deployment.
Issue: Complex nested filter groups
Lists with deeply nested filter logic (many AND/OR groups with sub-filters) import correctly but can take longer to parse. If a list import times out, retry it individually.
Issue: v2/v3 format discrepancies
HubSpot has two form API versions. JetStack AI handles both, but older forms created before HubSpot’s form builder update may have subtle structural differences. If a form import produces unexpected results, compare the imported configuration with the original in HubSpot and report any discrepancies to support.
Emails
Section titled “Emails”Issue: Generated layouts with complex smart content
Emails using drag-and-drop layouts with extensive smart content rules produce large configuration objects. These import correctly but may take longer to process. If an email times out, import it individually rather than as part of a large batch.
Templates
Section titled “Templates”Issue: Hyphenated module name references
Templates that reference custom modules with hyphenated names (e.g., my-custom-module) may occasionally have their module references parsed differently. If a template imports but its module references appear incorrect, verify the module names in the source portal and report the issue to support.
Issue: Site page vs. landing page detection
JetStack AI automatically determines whether a page is a site page or landing page based on its HubSpot configuration. In rare cases where a page was migrated between types in HubSpot, the detection may not match your expectation. The page data is still fully captured — the type label is informational and can be adjusted.
Partial Failure Recovery
Section titled “Partial Failure Recovery”When an import partially fails (some assets succeed, others do not), follow this process:
1. Check the Activity Log
Section titled “1. Check the Activity Log”Navigate to the Activity Log from the sidebar. Find your import task and click into it to see the detailed breakdown:
- Succeeded — assets that imported correctly and are in your library
- Failed — assets that encountered errors, with specific error messages
- Skipped — assets that were not processed (usually because a required dependency failed first)
2. Assess the Failures
Section titled “2. Assess the Failures”For each failed asset, determine:
- Is the failure transient (rate limit, timeout) or persistent (deleted asset, permissions)?
- Is the failed asset something you explicitly selected, or was it an auto-detected dependency?
- Do you actually need this asset, or can you proceed without it?
3. Retry Failed Assets
Section titled “3. Retry Failed Assets”You do not need to re-import everything. Select only the failed assets in a new import to fill in the gaps. Successfully imported assets from the original run remain in your library.
4. Verify Completeness
Section titled “4. Verify Completeness”After retrying, check your Asset Library to confirm all expected assets are present. Use the dependency view on your key assets to verify no dependencies are missing.
Getting Help
Section titled “Getting Help”If you encounter an error not listed here, or if a listed solution does not resolve your issue:
- Check the Activity Log for the full error message — it often contains specific details about what went wrong
- Verify your portal connection is active in Client Accounts
- Contact JetStack AI support with the import task ID from the Activity Log and the full error message
Next Steps
Section titled “Next Steps”- How Import Works — Understand the import process in detail
- Activity Log — Navigate and interpret activity entries
- Reconnecting a Portal — Fix OAuth connection issues