---
title: "How to Update Sanity Schema in Nextjs 15"
slug: "how-to-update-sanity-schema-in-nextjs-15"
published: "2025-05-15"
updated: "2025-12-21"
validated: "2025-10-20"
categories:
  - "Sanity"
llm-intent: "reference"
framework-versions:
  - "next.js@15"
  - "sanity@3"
  - "typescript@5"
  - "node@18"
status: "stable"
llm-purpose: "Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date."
llm-prereqs:
  - "General familiarity with the article topic"
llm-outputs:
  - "Completed outcome: Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date."
---

**Summary Triples**
- (local-testing, recommended-command, Use `npx sanity dev` to run the Studio locally and surface schema errors immediately.)
- (reference-errors, root-cause, Types are referenced but not imported, not registered in the main schema index, or misspelled.)
- (fix-reference, steps, Import the referenced type, register it in the schema index, and verify type name spelling.)
- (deploy-schema, after-testing, Deploy your Studio (sanity deploy) and then deploy the GraphQL API (sanity graphql deploy) if used.)
- (schema-registration, best-practice, Centralize and export all types from the schema index to avoid missing references.)
- (error-feedback, provided-by, `npx sanity dev` provides immediate and actionable error messages for schema issues.)

### {GOAL}
Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date.

### {PREREQS}
- General familiarity with the article topic

### {STEPS}
1. Follow the detailed walkthrough in the article content below.

<!-- llm:goal="Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date." -->
<!-- llm:prereq="General familiarity with the article topic" -->
<!-- llm:output="Completed outcome: Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date." -->

# How to Update Sanity Schema in Nextjs 15
> Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date.
Matija Žiberna · 2025-05-15

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.

## LLM Response Snippet
```json
{
  "goal": "Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date.",
  "responses": [
    {
      "question": "What does the article \"How to Update Sanity Schema in Nextjs 15\" cover?",
      "answer": "Learn how to update your Sanity schema in a Next.js 15 project with ease. Follow this step-by-step guide to keep your content structure up to date."
    }
  ]
}
```