Get help on Discord

Issue with creating IDs in Sanity.io data import

9 replies
Last updated: Mar 12, 2021
Odd one. I’m doing a data import and auto-generating ID’s so I can create ref’s on the fly.
This returns a bad request

[ { createOrReplace: { _type: "team", _id: "team-67" } } ]
This imported fine (underscore in 
_id
string)
[ { createOrReplace: { _type: "team", _id: "team_67" } } ]
Stranger still, it didn’t have the same issues with 
teamMember-123
or 
office-456
, only on this 
team-
type.
(This is via the HTTP mutations API)
AI Update

This is a genuinely puzzling issue, and I need to be honest: I cannot find documentation that definitively explains why team-67 specifically fails while other similar patterns work.

Based on the official Sanity documentation on document IDs, the documented rules are:

  • Maximum 128 characters
  • Can only contain a-zA-Z0-9._-
  • Cannot start with a - (dash)
  • Must not have more than one consecutive . character
  • Avoid prefixes like drafts. and versions. (used internally)

According to these rules, team-67 should be valid—it doesn't start with a dash, contains only allowed characters, and doesn't use reserved prefixes.

What's particularly strange about your situation:

  • team-67 fails ❌
  • team_67 works ✅
  • teamMember-123 works ✅
  • office-456 works ✅

This inconsistency suggests there might be:

  1. An undocumented validation rule specific to certain ID patterns
  2. A bug in the HTTP mutations API validation
  3. Some internal pattern matching that isn't publicly documented

My recommendations for moving forward:

Immediate fix: Use underscores instead of dashes in your auto-generated IDs since you've confirmed team_67 works. This is the quickest way to unblock your import.

Better long-term approach: Consider using a custom field for your identifiers rather than controlling _id. As the documentation recommends, create a customId field in your schema and let Sanity generate the _id:

{
  name: 'team',
  type: 'document',
  fields: [
    {
      name: 'teamId',
      type: 'string',
      validation: Rule => Rule.required()
    }
  ]
}

Get a definitive answer: Since this behavior contradicts the documented rules, I'd recommend contacting Sanity support directly with your specific examples. They should be able to explain whether this is a bug or an undocumented validation rule.

You can also test systematically by trying IDs like team-1, team-2, team-a, etc. to see if there's a specific pattern to the failures—this data would be valuable for a support ticket.

What was the error message? Could it be that you have a document with that ID already, but it has a different 
_type
?
Brand new dataset. Error was 400 bad request ... but I might not have been logging the full error. 
{
  error: {
    description: 'The mutation(s) failed: Cannot modify immutable attribute "_type"',
    items: [ { error: [Object], index: 10 } ],
    type: "mutationError"
  }
}
Just emptied the dataset and tried again. Confirmed, ID’s of 
team-123
give this error. ID’s with 
team_123
work.
Are you sure there isn't another document being created in your script/import that is using the same ID? The immutable attribute error happens when you try to change the 
_type
attribute for a document that aleady exists (even through 
createOrReplace
)
Yeah it’s possible my import is screwy! So, for prosperity I’ve just dumped out all the types and id’s that are being sent to be created… I don’t see how it’s importing the same ID in two types.
I have solved this for now by just using underscores.


[
    { _type: "office", _id: "office_roma" },
    { _type: "office", _id: "office_stanthorpe" },
    { _type: "office", _id: "office_toowoomba" },
    { _type: "team", _id: "team_39" },
    { _type: "team", _id: "team_40" },
    { _type: "team", _id: "team_41" },
    { _type: "team", _id: "team_42" },
    { _type: "team", _id: "team_43" },
    { _type: "team", _id: "team_44" },
    { _type: "team", _id: "team_45" },
    { _type: "team", _id: "team_46" },
    { _type: "team", _id: "team_47" },
    { _type: "team", _id: "team_48" },
    { _type: "team", _id: "team_49" },
    { _type: "team", _id: "team_57" },
    { _type: "team", _id: "team_58" },
    { _type: "team", _id: "team_64" },
    { _type: "team", _id: "team_67" },
    { _type: "teamMember", _id: "teamMember_1" },
    { _type: "teamMember", _id: "teamMember_108" },
    { _type: "teamMember", _id: "teamMember_11" },
    { _type: "teamMember", _id: "teamMember_110" },
    { _type: "teamMember", _id: "teamMember_111" },
    { _type: "teamMember", _id: "teamMember_114" },
    { _type: "teamMember", _id: "teamMember_115" },
    { _type: "teamMember", _id: "teamMember_121" },
    { _type: "teamMember", _id: "teamMember_123" },
    { _type: "teamMember", _id: "teamMember_124" },
    { _type: "teamMember", _id: "teamMember_130" },
    { _type: "teamMember", _id: "teamMember_132" },
    { _type: "teamMember", _id: "teamMember_136" },
    { _type: "teamMember", _id: "teamMember_137" },
    { _type: "teamMember", _id: "teamMember_138" },
    { _type: "teamMember", _id: "teamMember_139" },
    { _type: "teamMember", _id: "teamMember_14" },
    { _type: "teamMember", _id: "teamMember_142" },
    { _type: "teamMember", _id: "teamMember_145" },
    { _type: "teamMember", _id: "teamMember_146" },
    { _type: "teamMember", _id: "teamMember_147" },
    { _type: "teamMember", _id: "teamMember_148" },
    { _type: "teamMember", _id: "teamMember_149" },
    { _type: "teamMember", _id: "teamMember_150" },
    { _type: "teamMember", _id: "teamMember_151" },
    { _type: "teamMember", _id: "teamMember_154" },
    { _type: "teamMember", _id: "teamMember_155" },
    { _type: "teamMember", _id: "teamMember_156" },
    { _type: "teamMember", _id: "teamMember_157" },
    { _type: "teamMember", _id: "teamMember_158" },
    { _type: "teamMember", _id: "teamMember_160" },
    { _type: "teamMember", _id: "teamMember_19" },
    { _type: "teamMember", _id: "teamMember_23" },
    { _type: "teamMember", _id: "teamMember_29" },
    { _type: "teamMember", _id: "teamMember_3" },
    { _type: "teamMember", _id: "teamMember_31" },
    { _type: "teamMember", _id: "teamMember_34" },
    { _type: "teamMember", _id: "teamMember_4" },
    { _type: "teamMember", _id: "teamMember_46" },
    { _type: "teamMember", _id: "teamMember_50" },
    { _type: "teamMember", _id: "teamMember_55" },
    { _type: "teamMember", _id: "teamMember_58" },
    { _type: "teamMember", _id: "teamMember_59" },
    { _type: "teamMember", _id: "teamMember_6" },
    { _type: "teamMember", _id: "teamMember_61" },
    { _type: "teamMember", _id: "teamMember_65" },
    { _type: "teamMember", _id: "teamMember_66" },
    { _type: "teamMember", _id: "teamMember_7" },
    { _type: "teamMember", _id: "teamMember_70" },
    { _type: "teamMember", _id: "teamMember_76" },
    { _type: "teamMember", _id: "teamMember_77" },
    { _type: "teamMember", _id: "teamMember_78" },
]
If you are able to reproduce it using a simplified script, we'd love to see a GitHub issue on it!
Bah! Created a really simplified version of the same request with Sanity Client and a simplified Node Fetch mutation and they both now work. Must’ve been something with my previous imported data 😕 thanks for your time.
I got this error happening to me. Seemed to be an id conflict as suggested. I didn't realise that the ids are global rather than scoped to a type. the data source i was coming from (3rd party) obviously was doing them as scoped to types

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?