BuildWithMatija
  1. Home
  3. Blog
  5. Sanity
  7. How to Update Sanity Schema in Nextjs 15

How to Update Sanity Schema in Nextjs 15

A practical guide to updating your Sanity schema in modern Next.js 15 apps — simplified and developer-friendly.

15th May 2025··
Sanity
How to Update Sanity Schema in Nextjs 15

📋 Complete Sanity Development Guides

Get practical Sanity guides with working examples, schema templates, and time-saving prompts. Everything you need to build faster with Sanity CMS.

No spam. Unsubscribe anytime.

📄View markdown version
12

About the author

Matija Žiberna

Matija Žiberna

Full-stack developer, co-founder

AboutResume

Self-taught full-stack developer sharing lessons from building software and startups.

I'm Matija Žiberna, a self-taught full-stack developer and co-founder passionate about building products, writing clean code, and figuring out how to turn ideas into businesses. I write about web development with Next.js, lessons from entrepreneurship, and the journey of learning by doing. My goal is to provide value through code—whether it's through tools, content, or real-world software.

Contents

  • Common Schema Errors
  • Reference Errors
  • How to Fix Reference Errors
  • Other Common Schema Issues
  • Deploying Schema Changes
  • Step 1: Deploy to Studio
  • Step 2: Deploy GraphQL API (if applicable)
  • Troubleshooting Deployment Issues
  • Ensure You're in the Right Directory
  • Check Current Project Context
  • Reset GraphQL Deployment
  • Getting More Error Details
  • Schema Update Workflow Best Practices
  • Example: Adding a New Field to an Existing Schema
  • Conclusion
On this page:
  • Common Schema Errors
  • Reference Errors
  • How to Fix Reference Errors
  • Other Common Schema Issues
  • Deploying Schema Changes
Build with Matija logo

Build with Matija

Modern websites, content systems, and AI workflows built for long-term growth.

Services

  • Headless CMS Websites
  • Next.js & Headless CMS Advisory
  • AI Systems & Automation
  • Website & Content Audit

Resources

  • Case Studies
  • How I Work
  • Blog
  • CMS Hub
  • E-commerce Hub
  • Dashboard

Headless CMS

  • Payload CMS Developer
  • CMS Migration
  • Multi-Tenant CMS
  • Payload vs Sanity
  • Payload vs WordPress
  • Payload vs Contentful

Get in Touch

Ready to modernize your stack? Let's talk about what you're building.

Book a discovery callContact me →
© 2026Build with Matija•All rights reserved•Privacy Policy•Terms of Service
BuildWithMatija
Get In Touch

Sanity.io is a powerful content management system with a flexible schema that lets you model your content exactly how you need it. However, when updating your schema, you might encounter issues that prevent you from deploying your changes. This guide walks you through the process of updating your Sanity schema and troubleshooting common problems.

When you modify your Sanity schema, you need to:

  1. Test your changes locally
  2. Deploy your schema to Studio
  3. Deploy your GraphQL API (if you're using GraphQL)

Common Schema Errors

Before deploying any changes, it's crucial to test them locally:

bash
npx sanity dev

This command starts your local Sanity Studio and automatically checks your schema for errors. The development server provides immediate feedback about issues in your schema configuration.

Reference Errors

One of the most common issues occurs when one schema type references another that isn't properly defined or imported. For example:

typescript
// categoryType.ts with a reference error
export const categoryType = defineType({
  name: 'category',
  title: 'Category',
  type: 'document',
  fields: [
    // ...other fields
    defineField({
      name: 'featuredArticles',
      title: 'Featured Articles',
      type: 'array',
      of: [{ type: 'reference', to: [{ type: 'article' }] }],
      // Error: 'article' type is referenced but not imported or defined
    }),
  ],
});

How to Fix Reference Errors

Make sure to:

  1. Import all referenced types at the top of your schema file
  2. Register all schema types in your main schema index file
  3. Check for typos in type names

Corrected example:

typescript
// Import the referenced type
import { articleType } from './articleType';

export const categoryType = defineType({
  name: 'category',
  title: 'Category',
  type: 'document',
  fields: [
    // ...other fields
    defineField({
      name: 'featuredArticles',
      title: 'Featured Articles',
      type: 'array',
      of: [{ type: 'reference', to: [{ type: 'article' }] }],
      // Now correct because 'article' type is imported
    }),
  ],
});

Other Common Schema Issues

  • Circular references: Two schema types that reference each other directly
  • Naming conflicts: Multiple schema types with the same name
  • Invalid field configurations: Using options that don't exist for a specific field type
  • Missing required properties: Forgetting to include mandatory properties like name or type

Deploying Schema Changes

Step 1: Deploy to Studio

Once your schema passes local validation, deploy it to your Sanity Studio:

bash
npx sanity deploy

This makes your schema changes available in the hosted version of your Studio.

Step 2: Deploy GraphQL API (if applicable)

If you're using GraphQL with Sanity, you need to deploy your GraphQL API separately:

bash
npx sanity graphql deploy --dataset production

If you encounter a SchemaError during GraphQL deployment, it means there are still issues with your schema that need to be fixed.

Troubleshooting Deployment Issues

Ensure You're in the Right Directory

Run all Sanity commands from the directory that contains your sanity.config.js or sanity.config.ts file:

bash
# Check if you're in the right directory
ls -la sanity.config.ts

Check Current Project Context

To verify your project setup:

bash
npx sanity debug

Reset GraphQL Deployment

If you're having persistent issues with GraphQL deployment:

bash
# Force undeploy GraphQL
npx sanity graphql undeploy --force

# Then deploy again
npx sanity graphql deploy --dataset production

Getting More Error Details

Use the --verbose flag to get more detailed error information:

bash
npx sanity graphql deploy --dataset production --verbose

Schema Update Workflow Best Practices

  1. Make incremental changes: Update and test one schema type at a time
  2. Version control: Commit working versions before making major changes
  3. Test thoroughly: Check all affected parts of your content model in the Studio
  4. Be careful with destructive changes: Renaming or removing fields can lead to data loss
  5. Migrate data when needed: Use Sanity's migration tools for schema changes that affect existing data

Example: Adding a New Field to an Existing Schema

typescript
// Before
export const authorType = defineType({
  name: 'author',
  title: 'Author',
  type: 'document',
  fields: [
    defineField({
      name: 'name',
      title: 'Name',
      type: 'string',
    }),
    defineField({
      name: 'bio',
      title: 'Bio',
      type: 'text',
    }),
  ],
});

// After - adding a new social media field
export const authorType = defineType({
  name: 'author',
  title: 'Author',
  type: 'document',
  fields: [
    defineField({
      name: 'name',
      title: 'Name',
      type: 'string',
    }),
    defineField({
      name: 'bio',
      title: 'Bio',
      type: 'text',
    }),
    defineField({
      name: 'socialMedia',
      title: 'Social Media Links',
      type: 'array',
      of: [
        {
          type: 'object',
          fields: [
            { name: 'platform', type: 'string', options: { list: ['Twitter', 'LinkedIn', 'Instagram'] } },
            { name: 'url', type: 'url' },
          ],
        },
      ],
    }),
  ],
});

Conclusion

Updating your Sanity schema requires careful planning and testing. By following the steps outlined in this guide, you can make changes to your content model with confidence, minimize errors, and ensure a smooth deployment process. Remember that the local development environment is your best tool for catching issues early before they affect your production content.