Migration API - Undocumented UID caching

Developing with Prismic
,
1

Hi Prismic team,

I've been using the Migration API with Claude Code (AI coding agent) to migrate hardcoded Next.js pages into Prismic. The migration worked, but we hit three undocumented behaviors that cost significant debugging time:

  1. UID caching after deletion After deleting a document in the dashboard, the UID stays reserved for several minutes. Creating a new document with the same UID fails with "Document with this UID already exists" — even though the document is gone. No mention of this in the docs. We had to use temporary UIDs (e.g., trust-v4) and manually rename after merging the migration release.

  2. Silent 404 after successful publish - Migration completed, document showed as published in the dashboard, but the page returned 404 in production. No error anywhere. Root cause
    was a UID mismatch with the page route (migration used a temp UID). There's no validation or warning during publish that the UID doesn't match any known route.

  3. Slice variation not found — no pre-flight check - If the migration script references a slice variation that hasn't been pushed via SliceMachine, the migration fails with a generic error. The
    API doesn't validate referenced slices upfront or tell you which ones are missing. A pre-flight check would save a lot of back-and-forth.

The AI agent had full context of every failure and workaround but there was no way to automatically surface this to your team. Sharing manually in case it helps improve the Migration API docs and error handling.

Thanks,
Vivek

2

Hey @vivekk,

Welcome to the community, and thanks a lot for raising this! This kind of feedback is super helpful - we've shared it with the product team, and they'll take it into account when looking at improvements on the Migration API and how it works. In the meantime, we'll also look into documenting this better so debugging doesn't take as long, thanks for your contribution to this with this post :slight_smile: