InitialValue query fails but hardcoded reference works in Sanity schema

I can see you're struggling with using a GROQ query to set initial values dynamically. Let me clarify what's happening and provide the correct solution.

The Core Problem

The "Failed to resolve initial value" error occurs because field-level initialValue in your schema doesn't execute GROQ queries. When you write a GROQ query string in initialValue, it's just a string - nothing is actually running that query against your content.

Field-level initialValue can be:

• A static value
• A function that returns a value
• An async function that fetches from external APIs

But it doesn't have built-in access to query your Sanity content with GROQ.

The Correct Solution: Initial Value Templates

To set initial values based on GROQ queries, you need to use Initial Value Templates configured through the templates configuration in your sanity.config.ts:

// sanity.config.ts
import {defineConfig} from 'sanity'

export default defineConfig({
  // ... other config
  templates: (prev) => {
    return [
      ...prev,
      {
        id: 'serviceCodeList-with-vt',
        title: 'Service Code List (VT)',
        schemaType: 'serviceCodeList',
        value: async (params, context) => {
          // Use the context client to query your content
          const client = context.getClient({apiVersion: '2024-11-01'})
          
          // Query for the VT code list - get just the first result's ID
          const result = await client.fetch(
            `*[_type == 'codeList' && code match 'VT'][0]._id`
          )
          
          return {
            codeList: {
              _ref: result,
              _type: 'reference'
            }
          }
        }
      }
    ]
  }
})

Key points about this approach:

• Templates are defined in the templates configuration in your config file
• You use context.getClient() to get a Sanity client that can execute GROQ queries
• Add [0] to get the first result instead of an array
• Fetch just the _id and construct the reference object in the return value
• When users create a new document, they'll see "Service Code List (VT)" as an option in the document creation menu

About the "Blinking" Behavior

The strange blinking/bumping behavior you're seeing with the hardcoded _ref suggests a validation or rendering issue. This commonly happens when:

1. Type confusion - In your query result, you mentioned uncertainty about whether _type should be "serviceCodeList" or "codeList". In a reference object's structure, _type should always be "reference", never the document type name:

   {
     codeList: {
       _ref: '56d99a7f-bd55-4cd7-9eeb-d5b65fe63d5e',
       _type: 'reference'  // Always "reference", not the target document type
     }
   }

2. Schema mismatch - Verify your schema field is properly defined as a reference type to codeList documents

3. Validation loops - Studio might be repeatedly fetching the referenced document to validate it exists

The smooth behavior in tutorials comes from using Initial Value Templates properly - they resolve once during document creation, then the value is stored. No repeated fetching or validation loops.

Document vs Array

No, this isn't about document vs array - initialValue works for both. The issue is specifically about query execution context. Field-level initialValue can't execute GROQ queries; you need the template approach with context.getClient().

Alternative: Hardcode It (If Appropriate)

If the VT code list reference rarely changes, your hardcoded approach is actually perfectly valid:

initialValue: {
  codeList: {
    _ref: '56d99a7f-bd55-4cd7-9eeb-d5b65fe63d5e',
    _type: 'reference',
  }
}

This isn't a "query" but it's a legitimate pattern if the reference is essentially constant. The blinking might resolve once you ensure the _type is correctly set to "reference" and save/reopen the document.

My Recommendation

If you need dynamic lookup based on the code field matching "VT", use the Initial Value Templates approach in the templates configuration as shown above. If the VT reference is stable and won't change, the hardcoded field-level initialValue is simpler and perfectly acceptable - just make sure _type: 'reference' is correct and the schema field definition matches.