Skip to main content
Contentstack MCP profile hub is in general availability!

csdx import and export failures, and how to fix them

•
10 min read

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 ./export

The 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-blog

You 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.json

The 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-logs

Logs 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 \
  --yes

If 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 --yes

The 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,limit

The 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-report

To 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 --yes

Follow 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.