Describe your question/issue in detail: We are building a migration script to transfer Prismic documents from one repository to another using the Prismic Migration API. While we have a 92% success rate, 8% of documents are failing. The majority of failures (~6% of total) return only a generic "Internal server error" message with no additional debugging information. We can resolve the ~2% that have specific errors (embed issues, rich text issues), but the generic internal server errors provide no actionable details for troubleshooting.
Impacted feature: Prismic Migration API
What steps have you taken to resolve this issue already?
Analyzed failing documents for common patterns or characteristics
Successfully identified and resolved documents with specific error messages (embed/rich text issues)
Reviewed our migration script implementation for potential issues
Attempted to identify any patterns in the documents that return internal server errors
Errors:
{
"response": {
"message": "Internal server error"
}
}
Thanks for raising this. Completely agree, we’ve been running into some issues with the error messages on the Migration API. This is something we’re tracking (here) as we work on improving it and releasing it from beta, so it’s definitely on our radar and something we want to tackle sooner rather than later. I’ll add your post to the feature thread, so we can let you know once it’s been fixed.
If you need help with any specific situation where you can’t figure out what’s going on, please let me know and we’ll have a look on our side to see if our logs have more info. We’ll need timestamps, repository name, and any further information you can give us
Thank you for the insight and glad to hear that this is being worked through.
For our use case, we are seeing valid errors for many of the migrations that fail. It will point us to exactly what the issue may be such as rich text, an embed, and others that that need to be cleaned up on our end. However, would you have any advice for best next steps for the documents with unclear error messages?
As an example, here are two errors that we are working through. One with a clear error message and another with an unclear message. Please note that the emojis and console logging is added by our code.
Clear:
❌ Failed to migrate master document On-Demand Webinar: ESG 2.0: Enhancing Sustainability through Social Media (en-us): ParsingError: An invalid API response was returned
at WriteClient.fetch (file:/prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/Client.js:1214:15)
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
at async WriteClient.updateDocument (file:/prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/WriteClient.js:437:5)
at async WriteClient.migrateUpdateDocuments (file:/prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/WriteClient.js:224:7)
at async WriteClient.migrate (file:/prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/WriteClient.js:76:5)
at async migrateSingleDocument (webpack-internal:///(api)/./pages/api/staged/execute-migration.ts:111:36)
at async handler (webpack-internal:///(api)/./pages/api/staged/execute-migration.ts:415:34)
at async K (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/compiled/next-server/pages-api.runtime.dev.js:21:2946)
at async U.render (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/compiled/next-server/pages-api.runtime.dev.js:21:3827)
at async DevServer.runApi (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/next-server.js:554:9)
at async NextNodeServer.handleCatchallRenderRequest (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/next-server.js:266:37)
at async DevServer.handleRequestImpl (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/base-server.js:789:17)
at async /prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/dev/next-dev-server.js:331:20
at async Span.traceAsyncFn (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/trace/trace.js:151:20)
at async DevServer.handleRequest (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/dev/next-dev-server.js:328:24) {
url: 'https://migration.prismic.io/documents/aJVy9hMAACUAO0YY',
response: [
"We couldn't find data for the embed url https://vimeo.com/848352777?share=copy, error: 'invalid json response body at https://vimeo.com/api/oembed.json?format=json&url=https%3A%2F%2Fvimeo.com%2F848352777%3Fshare%3Dcopy reason: Unexpected non-whitespace character after JSON at position 4'"
]
}
Unclear:
❌ Failed to migrate master document 10 Top Couple Influencers on Instagram (en-us): PrismicError: An invalid API response was returned
at WriteClient.fetch (prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/Client.js:1249:11)
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
at async WriteClient.updateDocument (prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/WriteClient.js:437:5)
at async WriteClient.migrateUpdateDocuments (prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/WriteClient.js:224:7)
at async WriteClient.migrate (prismic-repository-cloner/node_modules/.pnpm/@prismicio+client@7.18.0/node_modules/@prismicio/client/dist/WriteClient.js:76:5)
at async migrateSingleDocument (webpack-internal:///(api)/./pages/api/staged/execute-migration.ts:111:36)
at async handler (webpack-internal:///(api)/./pages/api/staged/execute-migration.ts:415:34)
at async K (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/compiled/next-server/pages-api.runtime.dev.js:21:2946)
at async U.render (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/compiled/next-server/pages-api.runtime.dev.js:21:3827)
at async DevServer.runApi (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/next-server.js:554:9)
at async NextNodeServer.handleCatchallRenderRequest (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/next-server.js:266:37)
at async DevServer.handleRequestImpl (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/base-server.js:789:17)
at async /prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/dev/next-dev-server.js:331:20
at async Span.traceAsyncFn (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/trace/trace.js:151:20)
at async DevServer.handleRequest (/prismic-repository-cloner/node_modules/.pnpm/next@14.1.3_@babel+core@7.28.0_babel-plugin-macros@3.1.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/dev/next-dev-server.js:328:24) {
url: 'https://migration.prismic.io/documents/aJVzmRMAACYAO0ch',
response: { message: 'Internal server error' }
}
@vincent.nyamu At this stage for the unclear error messages, the best thing to do is reach out to Support. Hopefully we can fix the error messages soon, but in the meantime it requires going through logs on our end, so you can just give us more info in a ticket as it happens in the help portal here: Jira Service Management and we’ll get back to you then!
