Do this with AI
Install the dx-cli skill from Contentstack agent skills. Then ask your agent:
My csdx cm:stacks:import run finished but the target stack has no global fields and no taxonomies. Look at the export folder in ./export, tell me which CLI version made it and which modules it contains, and give me the import commands to run module by module. Don't run anything that writes to a stack.
New to this? Set up your AI workbench first.
csdx import and export failures, and how to fix them
csdx cm:stacks:export and cm:stacks:import move a whole stack in one command, which is great until a run dies halfway through a few thousand entries. The failures are usually not random. Node runs out of heap, the command waits for an answer nobody gives it, the export was made by a different CLI version, or the run hits the organization's rate limit.
This guide goes through the failures you are most likely to see with CLI 2.x, from local runs and CI. Every flag in it comes from csdx <command> --help on CLI 2.0.2.
What you'll learn
How to fix JavaScript heap out of memory on large stacks
Why an export or import seems to hang, and how to make it run unattended
Why global fields, extensions or taxonomies are missing after an import
How to throttle the CLI when it hits 429
How to audit an export and import it module by module
How to check a branch merge that the CLI reported as failed
Symptoms
What you see | Most likely cause |
|---|---|
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory | Node's default heap is too small for the stack |
The command sits at a prompt or stops printing progress, especially in CI | It is waiting for input: a Marketplace app prompt, a missing --data-dir or stack key, or the audit fix confirmation |
The import finishes, but global fields are missing | The export was made with CLI 1.x |
The import finishes, but a branch's content is missing | --data-dir points at the export root instead of the branch folder |
Taxonomies imported but not published | Environments weren't imported first, so the environment mapping is empty |
Marketplace-backed fields or extensions are missing | Private apps weren't re-created in the target organization |
429 responses, or Rate limit exceeded in the log | The CLI and other jobs together exceed the organization's rate limit |
cm:branches:merge exits with an error, but the branch looks merged | The merge job kept running after the CLI stopped watching it |
Why it happens
Contentstack concept: an export is a folder of JSON files, one subfolder per module (content_types, global_fields, entries, assets and so on). An import replays that folder against another stack in a fixed dependency order, and keeps a backup folder with UID mappings so references in later modules point at the new UIDs.
Most failures come from one of these:
The CLI is a Node.js process. Large entry and asset sets need more heap than Node gives a process by default.
Both commands are interactive when you leave things out. If a flag is missing, they ask. In CI nobody answers, so the run looks hung.
The folder layout changed between CLI 1.x and 2.x. CLI 2.x writes one file per content type and global field, and no longer writes branches.json. A 1.x export imported with 2.x loses data without telling you.
The CLI shares your organization's rate limit with everything else that calls the Content Management API.
Fix it
JavaScript heap out of memory
Give Node more heap with NODE_OPTIONS. The value is in megabytes:
NODE_OPTIONS="--max-old-space-size=8192" csdx cm:stacks:export \
-a source-stack \
--branch main \
--data-dir ./exportThe same works for cm:stacks:import. In CI, set it as a job environment variable so every csdx call gets it. Pick a value the machine actually has. 8192 on a runner with 7 GB of RAM trades a heap error for swapping or an OOM kill.
If more memory doesn't help, export less at once. --module exports one module, and --content-types limits which entries are exported:
csdx cm:stacks:export -a source-stack --branch main \
--module entries --content-types blog author \
--data-dir ./export-blogYou can also lower how much the CLI fetches and writes in parallel. The export config accepts fetchConcurrency and writeConcurrency (both default to 5). Put them in a JSON file and pass it with --config:
{
"fetchConcurrency": 2,
"writeConcurrency": 2
}csdx cm:stacks:export -a source-stack --branch main --data-dir ./export --config ./export-config.jsonThe export or import hangs
First find out whether it is stuck or waiting. Turn on debug logging and show it in the terminal:
csdx config:set:log --level debug --show-console-logsLogs go to ~/.contentstack/logs unless you set --path. If the last line is a question, the command is waiting for you. Make the run non-interactive:
Always pass --data-dir and either -a <alias> or -k <stack_api_key>. Without them, the CLI asks.
Pass --yes to answer the Marketplace app prompts.
On import, the audit step can find problems and ask before fixing them. --yes answers that too. If you audited the export yourself (see below), --skip-audit skips the step entirely.
Pass --branch explicitly on export. Without it, CLI 2.x exports the main branch only, and fails on a stack that has no branch called main.
If secured assets are enabled on your stack, pass --secured-assets on export. The docs list it as required in that case.
A non-interactive import for CI looks like this:
csdx cm:stacks:import -a target-stack \
--data-dir ./export \
--branch main \
--yesIf the logs show steady progress, the command isn't stuck, only slow. Large asset libraries take a long time. Export assets on their own with --module assets so you can see how long they take.
Global fields, extensions or taxonomies are missing after import
Check what you exported before you blame the import.
The export came from CLI 1.x. Importing a 1.x export with CLI 2.x skips every global field, with no error. Content types that use those global fields then fail or import incomplete. Re-export with CLI 2.x. You can tell a 1.x export by content_types/schema.json and global_fields/globalfields.json. CLI 2.x writes one file per UID instead, such as content_types/blog.json.
The data dir points at the wrong level. A 1.x export of several branches has one subfolder per branch and a branches.json at the root. The current importer doesn't read branches.json, so point --data-dir at the branch folder:
csdx cm:stacks:import -a target-stack --data-dir ./export/main --branch main --yesThe reverse problem bites on export. CLI 2.x writes straight into --data-dir with no branch subfolder, so exporting two branches into the same folder overwrites the first one. Use a folder per branch.
Taxonomies imported but not published. Taxonomy publishing uses the environment mapping from the import. If environments weren't imported first, the mapping is empty, and the import skips taxonomy publishing with a warning. Also note that without the taxonomy localization feature on your plan, taxonomies are exported without their localized terms.
Extensions and Marketplace apps. If you decline to re-create private Marketplace apps during the import, the CLI skips installing them, and fields that depend on them can fail. Private apps belong to an organization, so a target stack in another organization needs its own copy.
Things the CLI never moves. Users and releases can't be exported or imported. With a management token alias (-a), stack settings are skipped too. Use csdx auth:login if you need them.
429 during import
The CLI throttles itself to a share of your organization's rate limits. config:set:rate-limit reads the limits from your organization's plan and stores how much of each the CLI may use. The default is 50 percent:
csdx config:get:rate-limit
csdx config:set:rate-limit --org <org_uid> --utilize 30,30 --limit-name getLimit,limitThe limit names are limit, getLimit and bulkLimit. Lower the percentage if other things call the Content Management API at the same time, such as a second pipeline, an Automate workflow or a publish webhook that triggers builds. Reset with --default.
This setting lives in the CLI config on the machine that runs csdx. A CI runner starts with a fresh config, so run config:set:rate-limit in the job before the import. For the bigger picture on 429s in builds and bulk publishing, read fix 429 rate limit errors in builds, imports and bulk publish.
Audit the export before you import
cm:stacks:audit checks an export folder for broken references, missing global fields and invalid field data, without touching any stack:
csdx cm:stacks:audit -d ./export --report-path ./audit-reportTo fix what it finds, run audit:fix with a backup copy of the original data:
csdx cm:stacks:audit:fix -d ./export \
--report-path ./audit-report \
--copy-dir --copy-path ./export-fixed--fix-only limits the fixes, for example --fix-only=reference,global_field. Import runs the same audit fix automatically unless you pass --skip-audit. One side effect to know: the audit step removes all workflow branches except the one you import into.
Import module by module
When a full import fails late, don't start over. Import the remaining modules one at a time with --module, and pass the same --backup-dir every time so each module finds the UID mappings the earlier ones wrote:
csdx cm:stacks:import -a target-stack --data-dir ./export --branch main \
--module environments --backup-dir ./import-backup --yes
csdx cm:stacks:import -a target-stack --data-dir ./export --branch main \
--module taxonomies --backup-dir ./import-backup --yesFollow the documented order: locales, environments, assets, taxonomies, extensions, marketplace apps, webhooks, global fields, content types, workflows, entries, labels, custom roles, publishing rules, Personalize, Composable Studio. If a module already exists in the target, --replace-existing replaces it. That overwrites data in the target stack, so take an export of the target first.
To skip publishing while you check the result, add --skip-entries-publish, --skip-assets-publish or --skip-taxonomy-publish.
Branch merge reports a failure
csdx cm:branches:merge submits a merge job to Contentstack and then watches it. The job and the CLI are separate. If the CLI stops watching, loses its connection or reports an error, the merge can still be running or already be done.
Get the merge UID from the CLI output and check the job:
csdx cm:branches:merge-status -k <stack_api_key> --merge-uid <merge_uid>Only trust a failure the job itself reports. Two more things to keep in mind:
A merge covers content types and global fields. It doesn't move entries.
By default the merge creates a revert branch first. --no-revert skips that, so leave it off unless you have another way back.
Use --export-summary-path to save the merge plan, review it, then apply exactly that plan with --use-merge-summary. The guide on safe content model changes with branches and aliases covers the full branch workflow.
Check that it worked
Compare the module folders in your export with the target stack: count content types, global fields and taxonomies on both sides.
Read the import log for skipped modules and warnings, such as skipped taxonomy publishing.
Re-run cm:stacks:audit on a fresh export of the target. A clean report means references survived the move.
For a merge, cm:branches:merge-status should show the job as complete, and csdx cm:branches:diff between the two branches should show nothing left to merge.
Prevent it
Pin the CLI version in CI (npm install -g @contentstack/cli@<version>) and export and import with the same version.
Run every csdx command in CI with --data-dir, -a or -k, --branch and --yes, so nothing can wait for input.
Set NODE_OPTIONS=--max-old-space-size=... on the job, and config:set:rate-limit before the import.
Audit exports before you import them, and keep one folder per branch.
Keep a backup export of the target before any --replace-existing run.
If you want to know where these commands come from, or add one your team is missing, read every csdx command is a plugin and write your own csdx plugin.
Key takeaways
JavaScript heap out of memory is fixed with NODE_OPTIONS="--max-old-space-size=8192", or by exporting less per run with --module and --content-types.
A "hung" run is usually a prompt. Pass --data-dir, -a, --branch and --yes, and turn on csdx config:set:log --level debug --show-console-logs to see where it stopped.
Missing global fields after import usually means a CLI 1.x export. Re-export with 2.x.
Import environments before taxonomies, and reuse one --backup-dir when you import module by module.
Throttle with csdx config:set:rate-limit --utilize, and set it on the CI runner, not only on your laptop.
A merge is a job. Check csdx cm:branches:merge-status before you treat it as failed.
Frequently asked questions
How do I give csdx more memory for a large export or import?
Set NODE_OPTIONS before the command, for example NODE_OPTIONS=--max-old-space-size=8192 csdx cm:stacks:export. The value is in megabytes.
Why did my import skip all global fields without an error?
The export was most likely made with CLI 1.x. The current importer skips every global field in a 1.x export without a warning, so re-export with CLI 2.x.
Can I import one module at a time?
Yes. Use --module with --backup-dir, follow the documented module order, and reuse the same backup folder so later modules find the UID mappings of earlier ones.
How do I stop csdx from hitting 429 errors?
Run csdx config:set:rate-limit with a lower --utilize percentage for your organization, and avoid running other API-heavy jobs against the same organization at the same time.
The CLI said my branch merge failed, but did it?
Check the merge job with csdx cm:branches:merge-status and the merge UID. The merge runs as a job in Contentstack, so its status is what counts, not the CLI's exit.