"Hyperlink span must contain a 'data' field with link data"

[chibu (Chibu O)]

Hello,
Currently working on migrating content between two Prismic repositories and using the createDocumentFromPrismic() api. Sample code snippet:

const uploadAssetsUsingPrismicClient = async (docsObj) => {
    const writeClient = prismic.createWriteClient(config.destRepo,
        {
            writeToken: process.env.AUTH_TOKEN_DEST,
            migrationAPIKey: <<apiKeyFoundInDocs>>,
        });
    
    const migration = prismic.createMigration();
    const d = docsObj[0];
    migration.createDocumentFromPrismic(d, d.data.title);

    await writeClient.migrate(migration, {
        reporter(e) {
            console.log('e.pending', e);
            console.log('e.migrated', e);
        },
    });
}

After running script, I get this error:

{
      property: 'data.body_content.0.spans.0',
      value: {
        start: 87,
        end: 110,
        type: 'hyperlink',
        data: { link_type: 'Any' }
      },
      error: "Hyperlink span must contain a 'data' field with link data"
    },

The below JSON object snippet is part of the whole document JSON fetched from the Prismic REST API and passed into the createDocumentFromPrismic function mentioned above (actual text content redacted):

"body_content": [
        {
          "type": "paragraph",
          "text": "Social media never sleeps — xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxxxxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxxxxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxxxxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxxxxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxxxxxxxxxxx",
          "spans": [
            {
              "start": 87,
              "end": 110,
              "type": "hyperlink",
              "data": {
                "id": "YSYcDBAAACMAic6a",
                "type": "blog_post",
                "tags": ["pillar"],
                "lang": "en-us",
                "slug": "social-media-xxx-xxxxx",
                "first_publication_date": "2021-09-20T08:17:20+0000",
                "last_publication_date": "2025-02-10T12:43:51+0000",
                "uid": "social-media-management",
                "link_type": "Document",
                "isBroken": false
              }
            },
            { "start": 154, "end": 173, "type": "strong" }
          ],
          "direction": "ltr"
        },

What am I doing wrong?
Thanks

[Ezekiel (Ezekiel Ravidat)]

Hi @chibu

The error is saying that the hyperlink span inside body_content is missing or has invalid link data — specifically, the link_type "Any" is not valid in this context.

Your actual span data looks fine to me, but I think Prismic expects a very specific shape for hyperlink span data —*and createDocumentFromPrismic() expects it in "rich text" format, not in the format returned by the REST API.

The problem is likely coming from the way the REST API gives you hyperlink data — it includes more document metadata than necessary. The Migration API wants a minimal shape like this:

"data": {
  "link_type": "Document",
  "id": "YSYcDBAAACMAic6a",
  "type": "blog_post",
  "uid": "social-media-management"
}

So could you try to strip away the extra properties like slug, tags, lang, etc., and just keep the essential fields? We'll see if that helps it go through.

Let me know!

[chibu (Chibu O)]

Thank you @Ezekiel, I'll try it out and let you know!

[chibu (Chibu O)]

Thank you so much @Ezekiel, that worked! So sorry I haven't responded until now as I was away on vacation.

The only other thing left is that the related items section of the migrated documents seem to not load properly within the Prismic editor. First, only the document id is displayed and then when you click on them. You see a message that says:

Request failed
An error occurred while fetching the linked page.
I've attached screenshots of what the section looks like.

Thanks a lot!

[Ezekiel (Ezekiel Ravidat)]

Hi @chibu,

Happy to hear that it worked (and hope you enjoyed your vacation! )

Are the document linked the proper ones, and are they being displayed properly in your website? If you try to search for the right document when you click through and hit try again, does it work then?

[chibu (Chibu O)]

Hi @Ezekiel, thanks for your prompt response!

That's a great question. I know that the documents currently linked in the related items section have not been migrated yet. That's because so far I have only migrated a couple random documents into a sandbox repo to understand how it works before I proceed with the live repo. All the documents in the sandbox are still in the Migration Release and not published yet.

How will these document ids nested within the related_items section be updated though? Because those ids map to existing documents and the ids will no longer be valid after a successful migration. Can the simple call to migration.createDocumentFromPrismic() and writeClient.migrate() handle all of the document id updates, or do I need to write extra code to migrate the content relationships?

Thank you!

[Ezekiel (Ezekiel Ravidat)]

Hey @chibu,

This might help: Migrating to Prismic - Documentation - Prismic

You do have to update relationships, as indeed these documents won't be automatically updated. During the migration process, you need to manually map old/new documents.

Here's the general approach:

1. Create a mapping between old and new document IDs.

• When you migrate each document, save its original Prismic ID (uid or old id) along with the new ID generated in the target repo.
• This can be stored in a simple Map<string, string> (oldId → newId).

2. During the migration of related documents:

• Replace the old IDs in the related field with the new ones from your mapping.
• If the related document hasn’t been migrated yet, skip or mark it temporarily and backfill later once it has been.

3. If you migrate in batches, do a second pass to backfill relationships.

• Once all documents are migrated and you have a complete mapping, you can run a second migration script that updates related with the correct new document references.

[chibu (Chibu O)]

Ok, thanks for confirming that I would have to stop being lazy and just write the code .

You have been very helpful @Ezekiel , and I appreciate it. Have a great rest of your day!

[Ezekiel (Ezekiel Ravidat)]

Fair of you to check first, if there's a way to code less rather than more it's always good to take it Happy to help @chibu, and good luck with the coding! If you run into more issues feel free to come back to this thread

[vincent.nyamu]

@Ezekiel

3. If you migrate in batches, do a second pass to backfill relationships.

• Once all documents are migrated and you have a complete mapping, you can run a second migration script that updates related with the correct new document references.

Hey Ezekiel, wanted to follow up and fully understand how the team should be going about updating the documents once they are migrated and he have a complete mapping.

It seems we cannot read the migration release and there isn’t much documentation on how to do so. We’re told to use migraiton.updateDocument() but that seems to be limited in scope.

[Edu (jose.rodriguez@prismic.io)]

Hey Vincent, we see you have a ticket with us through Support. Our team will assist directly there.

For anyone else finding this thread, as of September 2025, the Migration API is write-only. You’ll need to use the Content API to read any content (including migration releases) from the target-migration repository.