Sanity GraphQL: Duplicate type name error with reference and inline types

This is a known issue with Sanity's GraphQL schema generation that occurs when you try to use the same type both as a document type (for standalone documents that can be referenced) and as an inline object type within an array. When GraphQL generates the schema, it creates a union type for the array that conflicts with the document type name, resulting in the "Found duplicate type names: Cat" error.

The Root Cause

The problem happens because you're using cat in two different ways in your schema:

1. As a standalone document type that can be referenced
2. As an inline object within the cats array in the person document

When you include both { type: 'reference', to: [{ type: 'cat' }] } and { type: 'cat' } in the same array, GraphQL tries to create a union type named "Cat" for the array items, but that name already exists as the document type.

The Recommended Solution

Create separate types for the document and the inline object. Here's the cleanest approach:

import createSchema from "part:@sanity/base/schema-creator";
import schemaTypes from "all:part:@sanity/base/schema-type";

// Shared fields that both types will use
const catFields = [
  {
    title: 'Name',
    name: 'name',
    type: 'string'
  }
];

// Document type for standalone cat documents
const cat = {
  title: 'Cat',
  name: 'cat',
  type: 'document',
  fields: catFields
};

// Object type for inline cats
const catObject = {
  title: 'Cat (Inline)',
  name: 'catObject',
  type: 'object',
  fields: catFields
};

const person = {
  title: 'Person',
  name: 'person',
  type: 'document',
  fields: [
    {
      title: 'Name',
      name: 'name',
      type: 'string'
    },
    {
      title: 'Cats',
      name: 'cats',
      type: 'array',
      of: [
        {
          type: 'reference',
          title: 'Cat Reference',
          to: [{ type: 'cat' }]
        },
        { type: 'catObject' }  // Use the separate object type
      ],
    }
  ]
};

export default createSchema({
  name: "default",
  types: schemaTypes.concat([cat, catObject, person])
});

This approach gives you the functionality you want (both referencing existing cats and creating inline cats) without the naming conflict. The inline cats created with catObject will only exist within the person document, while cat documents remain globally available and referenceable.

About Your Workaround

Your workaround of adding a dummy workaround type to the reference array is clever! By making the reference point to multiple types [{ type: 'cat' }, { type: 'workaround' }], you force GraphQL to generate a different union type name like "CatOrWorkaround" instead of just "Cat", which avoids the naming collision. While it works, the separate object type approach above is cleaner and more semantically correct.

Important Note About Creating References

It's worth mentioning that Sanity doesn't currently support creating new referenced documents directly from within another document's reference field (sometimes called "creating references in place"). When you use a reference field, you can only select from existing documents. The inline object approach creates data within the parent document itself, not as a separate referenceable document.

If you need the ability to create new standalone cat documents that can be referenced elsewhere, users will need to create those separately in the Studio first, then reference them in the person document.