Troubleshooting

“Missing section / entry type / group / volume”

The target is missing schema the package needs. Transport moves content, not schema — deploy your Project Config to the target first so the required sections, entry types, category groups, and volumes exist, then run the import again. This is exactly what pre-flight validation is protecting you from.

A field didn’t import

Unsupported field types are skipped with a warning in storage/logs/transport.log rather than failing the whole import. Check the log to see which field was skipped. If it’s a custom or third-party field that embeds element references, you can add support by registering a handler — see Extending.

“Could not generate a unique URI based on the URI format”

The target already has that content under a different UID — most often a single, whose URI format has no {slug} token for Craft to make unique. Transport recognizes this case and updates the existing element instead of adding a second one. If you see this error, either Match existing content on import is switched off in settings, or you’re on a release before 5.1.0.

A queued export or import never finishes

Control panel runs go to Craft’s queue, which needs something to run it. Check Utilities → Queue Manager for a stuck or failed job, and make sure the queue is actually being run — Craft’s built-in web-based runner, or craft queue/listen under a process manager. Console runs are never queued, so craft transport/import is a good way to bypass the queue entirely.

“Transport is installed with schema version of 1.1.0 while 1.0.0 was expected”

You updated to a release that adds a database column, and Craft records the new schema version in your project config when the migration runs. If the environment also had pending project config changes, craft up applies config before writing the config files back out, stops on the version mismatch, and returns before the new version reaches config/project/. Your database is already migrated at that point — only the files are behind.

Run craft project-config/diff to see what’s pending. If none of it matters, craft project-config/write regenerates the files with the new version. If you need those changes applied, set plugins.transport.schemaVersion to the new version in config/project/project.yaml so the two agree, then run craft up again. Either way, commit the updated project config.

No completion email arrived

Transport sends through Craft’s mailer — test it under Settings → Email. Also confirm the run was started by a user with an email address and that Email me when it finishes was ticked. Notification failures are logged to storage/logs/transport.log and never fail the run itself, so the import or export still completed.

References point to the wrong element (or nothing)

Transport resolves references by UID, so the linked element must also exist in the target — either already present, or included in the same package. If a relation comes through empty, confirm the referenced element was part of the export and that its UID matches across environments.

An import went wrong

Roll it back. Every import is snapshotted first, so from Transport → History you can restore updated elements and remove created ones with one click. The rollback is itself reversible. See History & Rollback.

The package is too large to upload

Raise Max package size in Settings → Transport, and check your server’s upload_max_filesize and post_max_size. Alternatively, export metadata only (turn off Include asset files) when the files already exist in the destination, or use the CLI, which isn’t bound by the upload limit.

Neo or Super Table content behaves unexpectedly

Those two handlers are experimental — they ship but haven’t been exercised against live installs. Test on a staging copy before relying on them in production, and report what you find. See Integrations.

Some Craft Commerce data didn’t come across

Commerce products and variants are supported and tested, but inventory levels, catalog pricing, and orders are intentionally out of scope — that data is environment-specific. Deploy product types via Project Config first, then import the products themselves. See Integrations.

Still need help?

Open an issue on GitHub with details about your problem — including the relevant lines from storage/logs/transport.log — and we’ll help you out.