Singleton document migration fails with "references non-existent document" error

You're hitting a documentReferenceDoesNotExistError because your landingPage singleton document contains a reference field pointing to a document (ID 6e064ed9-c668-4084-a803-8166a5a970f1) that doesn't exist in your production dataset. When using --replace, Sanity validates all document references during import to maintain referential integrity, and the operation fails if any referenced documents are missing.

You're correct that this has nothing to do with your desk structure configuration from the singleton guide. The .documentId("landingPage") in your structure file is just for UI navigation—it doesn't create actual document references.

The "landingPage" in the error is the _id of your singleton document (which matches its schema type name, as configured in the guide). The document itself contains a reference field pointing to a non-existent document.

Solutions

1. Import All Documents (Recommended)

The most straightforward approach is to import your entire staging dataset, which includes both the singleton and all documents it references:

# Export from staging
sanity dataset export staging staging-export.tar.gz

# Import to production with --replace
sanity dataset import staging-export.tar.gz production --replace

This ensures all referenced documents exist before the singleton is validated.

2. Import Without --replace (Merge Mode)

If you don't need to completely replace the production dataset, import without the --replace flag. This merges the staging content into production without strict validation:

sanity dataset import staging-export.tar.gz production

Note: This only works if there are no document ID conflicts, or if you're okay with the imported documents overwriting existing ones.

3. Remove the Problematic Reference

If the reference isn't needed or is outdated, clean it up in staging first:

• Open your staging Studio
• Navigate to the landingPage document
• Find the reference field pointing to the missing document
• Remove or update the reference
• Export and import again

4. Investigate the Reference

To identify which field contains the problematic reference:

# Export your staging dataset
sanity dataset export staging staging.tar.gz

# Extract and search for the reference
tar -xzf staging.tar.gz
grep "6e064ed9-c668-4084-a803-8166a5a970f1" data.ndjson

This shows you the exact document structure and which field contains the reference. You can then decide whether to include the referenced document in your export or remove the reference.

5. Use a Fresh Dataset

If you need a complete replacement and don't mind losing production data:

# Delete and recreate the production dataset (WARNING: destroys all data)
sanity dataset delete production
sanity dataset create production

# Import without --replace since the dataset is empty
sanity dataset import staging-export.tar.gz production

Why This Happens

The --replace flag enforces strict referential integrity validation. The most common cause is exporting only specific documents (like just your singleton) without including the documents they reference. The solution is typically to export the complete dataset or clean up the references before exporting.