Sanity "Unsupported path segment {}" error with array of references
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?
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:
- If you have few documents: Manually add
_keyvalues to each array item through the Studio or a migration script - For many documents: Write a migration script that patches all affected documents, adding unique keys to array items
- 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 thread9 replies
Was this answer helpful?
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.
