Sanity Studio displaying errors after installation in Next.js project
I understand you've installed Sanity into your Next.js project but are encountering errors when trying to run the studio. Since you haven't provided the specific error messages, I'll cover the most common setup issues and their solutions based on the official documentation.
Common Setup Issues and Solutions
1. Studio Route Configuration
The most frequent issue is incorrect route setup. For Next.js App Router, your studio route should be structured like this:
File location: app/studio/[[...tool]]/page.tsx
import { NextStudio } from 'next-sanity/studio'
import config from '../../../sanity.config'
// This exports metadata for proper mobile rendering and SEO
export { metadata } from 'next-sanity/studio/metadata'
export default function StudioPage() {
return <NextStudio config={config} />
}Key points:
- The catch-all route
[[...tool]]is crucial for Studio navigation to work - The
metadataexport handles necessary meta tags - Your
sanity.config.tsmust havebasePath: '/studio'matching your route
2. Configuration File Setup
Your sanity.config.ts should be at the root of your project (not inside /app or /src):
'use client'
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
export default defineConfig({
basePath: '/studio', // Must match your route path
projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
plugins: [structureTool()],
schema: {
types: [] // Add your schema types here
}
})3. Environment Variables
Ensure your .env.local file has these variables with the NEXT_PUBLIC_ prefix (required for browser access):
NEXT_PUBLIC_SANITY_PROJECT_ID=your-project-id
NEXT_PUBLIC_SANITY_DATASET=production4. CORS Configuration
You must add your domain to Sanity's CORS origins settings with authenticated requests enabled. This is easy to forget but critical. For local development, add:
http://localhost:3000(or whatever port you're using)
5. Dependencies
Verify you have the required dependencies installed:
npm install next-sanity sanity styled-componentsFor npm v7+, peer dependencies should install automatically. If you're using an older version or encountering module errors, you may need to install them manually.
6. Pages Router Setup (if applicable)
If you're using the Pages Router instead, the setup is different:
File location: pages/studio/[[...index]].tsx
import Head from 'next/head'
import { NextStudio } from 'next-sanity/studio'
import { metadata } from 'next-sanity/studio/metadata'
import config from '../../sanity.config'
export default function StudioPage() {
return (
<>
<Head>
{Object.entries(metadata).map(([key, value]) => (
<meta key={key} name={key} content={value} />
))}
</Head>
<NextStudio config={config} />
</>
)
}Debugging Steps
- Check the browser console for specific JavaScript errors
- Verify the route - Navigate to
http://localhost:3000/studio - Check your terminal for build-time errors
- Clear Next.js cache:
rm -rf .nextand rebuild - Verify Node.js version - Studio v3 requires Node.js 20+
Get More Specific Help
To get more targeted assistance, please share:
- The exact error messages from your browser console and terminal
- Your Next.js version (check
package.json) - Whether you're using App Router or Pages Router
- The file structure of your studio route
The official embedding documentation and next-sanity GitHub repository have additional troubleshooting information and examples you can reference.
Show original thread5 replies
Was this answer helpful?
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.
