Get help on Discord

Sanity "Unsupported path segment {}" error with array of references

9 replies
Last updated: Nov 30, 2025
I am experiencing an issue in Sanity Studio where I am getting an "Unsupported path segment {} " error when trying to view or edit documents of type card. I have a card schema where there is a codes field which is an array of references to code documents.Here's the card schema for your reference:




export default {
  name: 'card',
  title: 'Card',
  type: 'document',
  fields: [
    {
      name: 'title',
      title: 'Title',
      type: 'string',
    },
    {
      name: 'image',
      title: 'Image',
      type: 'image',
    },
    {
      name: 'rarity',
      title: 'Rarity',
      type: 'reference',
      to: [{type: 'rarity'}],
    },
    {
      name: 'series',
      title: 'Series',
      type: 'reference',
      to: [{type: 'series'}],
    },
    {
      name: 'totalCards',
      title: 'Total Cards',
      type: 'number',
    },
    {
      name: 'codes',
      title: 'Codes',
      type: 'array',
      of: [{type: 'reference', to: [{type: 'code'}]}]
    },
  ],
}


The new codes are correctly added to the codes array of the card documents and there doesn't seem to be any orphaned reference. I'm getting the error after executing a script that creates code documents and then adds a reference to them in the codes array of card documents.

Do you have any insight into what could be causing this error and how it could be resolved?
AI Update

The "Unsupported path segment {}" error you're encountering is a common issue that occurs when array items in Sanity documents are missing the required _key property. Based on the Sanity community discussions, this is exactly what's happening with your script.

The Problem

When you programmatically add items to an array field (like your codes array), each item must have a unique _key property. Sanity uses these keys internally to track array items and maintain proper document structure. Without them, the Studio can't properly render or edit the documents, resulting in the "Unsupported path segment {}" error.

The Solution

You need to ensure your script generates _key values when adding references to the codes array. You have two options:

Option 1: Use autoGenerateArrayKeys (Recommended)

When using the Sanity client to perform mutations, set the autoGenerateArrayKeys option to true:

client
  .patch(documentId)
  .setIfMissing({codes: []})
  .append('codes', [{_type: 'reference', _ref: codeDocumentId}])
  .commit({autoGenerateArrayKeys: true})

Option 2: Manually Generate Keys

Alternatively, manually add unique _key values to each array item:

import {uuid} from '@sanity/uuid'

const newCodeReference = {
  _type: 'reference',
  _ref: codeDocumentId,
  _key: uuid() // or any unique string generator
}

Fixing Existing Documents

The autoGenerateArrayKeys option will only fix documents going forward. For existing documents with missing keys, you have a few approaches:

  1. If you have few documents: Manually add _key values to each array item through the Studio or a migration script
  2. For many documents: Write a migration script that patches all affected documents, adding unique keys to array items
  3. Nuclear option: If the data isn't critical, delete and recreate the affected documents

Make sure the keys are unique within each document's array. The keys don't need to be globally unique, just unique within their parent array.

This should resolve your issue completely!

Show original thread
9 replies

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?