Troubleshooting and next steps
Most migration failures are recoverable. This chapter covers the common cases and where to go once the migration is stable.
What you'll learn
How to recover from the most common failures
When to split content and code into separate passes
What to do after the migration is complete
Common failures
The Contentstack token expired mid-run
A long import can outlast the OAuth token. The log shows a 401 about an invalid or expired token. Re-authenticate and re-run; the create command is safe to re-run because it creates a fresh stack each time:
csdx auth:login --oauthContentful login is not recognized
If the migration cannot resolve your Contentful management token, run contentful login again, complete the browser flow, and retry. Verify access to the space with contentful space list.
Node is too old
If a command fails with a Node version error, the shell resolved a Node below 20. Install and select Node 20 or higher with nvm install 22 && nvm use 22, then confirm with node --version before retrying.
The import target stack is not empty
migrate:import requires an empty destination stack. Either point it at a fresh stack or let it create one with --org.
Webhooks are missing after import
The importer processes webhooks in batches, and a known issue can skip webhooks after the first batch. Check the imported webhook count against the source and recreate any missing ones through the Contentstack Management API.
When to split content and code
The automated code migration is strong on basic and mid-complexity sites. On a heavily customized architecture, run the content migration and the code migration as separate supervised passes rather than expecting one autonomous run to handle everything. Review the planned changes before applying them, and lean on the TODO(migration) comments.
Next steps
After the migration is stable:
Start the app with the new CS_* environment variables and confirm pages render against Contentstack.
Invite your team, set up roles, and configure publishing workflows in the Contentstack dashboard.
Set up webhooks and automation for deploys and publish events, and re-enter any webhook secrets.
Review the Contentstack Delivery SDK, GraphQL, and Live Preview references for the patterns your app uses.
Support for additional source platforms such as Sanity, Storyblok, and Strapi is planned. The architecture adds a new source by implementing an export adapter and a conversion adapter, so the workflow in this guide stays the same as new sources arrive.
Key takeaways
Most failures are recoverable; re-running migrate:create is safe.
Node below 20 and a non-empty destination stack are the most common blockers.
Split content and code into separate passes for complex architectures.
After migration, verify the live site, configure the dashboard, and re-enter webhook secrets.
Frequently asked questions
What should I do if the Contentstack OAuth token expires during a migration run?
Re-authenticate with `csdx auth:login --oauth` and re-run the migration. Re-running `migrate:create` is safe because it creates a fresh stack each time.
How do I fix an unrecognized Contentful login during migration?
Run `contentful login` again, complete the browser flow, and retry. Confirm access by running `contentful space list`.
Which Node.js version is required for the migration tooling?
Use Node 20 or higher. With nvm, run `nvm install 22 && nvm use 22`, then verify with `node --version`.
Why does `migrate:import` fail when the destination stack is not empty?
`migrate:import` requires an empty destination stack. Point it at a fresh stack or let it create one by providing `--org`.
What should I check if webhooks are missing after import?
Compare the imported webhook count to the source and recreate missing webhooks via the Contentstack Management API. Re-enter webhook secrets as part of post-migration setup.