Sanity & NextJS environment variables not working

I can help you troubleshoot environment variable issues with your Sanity & Next.js setup! This is a common pain point because the two systems use different prefixes.

The Two-Prefix System

When you have Sanity Studio embedded in a Next.js app, you need to understand that two different prefix systems are at play:

For Next.js Variables

Variables that need to be accessible in the browser must use the NEXT_PUBLIC_ prefix:

NEXT_PUBLIC_SANITY_PROJECT_ID=your-project-id
NEXT_PUBLIC_SANITY_DATASET=production

For Sanity Studio Variables

If you're running Sanity Studio (either standalone or embedded), variables need the SANITY_STUDIO_ prefix:

SANITY_STUDIO_API_PROJECT_ID=your-project-id
SANITY_STUDIO_API_DATASET=production

Common Problems & Solutions

Problem 1: Embedded Studio in Next.js When you embed Sanity Studio in Next.js (like at /studio route), you often need both prefixes for the same values:

# For Next.js pages/components
NEXT_PUBLIC_SANITY_PROJECT_ID=abc123
NEXT_PUBLIC_SANITY_DATASET=production

# For embedded Studio
SANITY_STUDIO_API_PROJECT_ID=abc123
SANITY_STUDIO_API_DATASET=production

Problem 2: Server-side vs Client-side Remember that NEXT_PUBLIC_ variables are exposed to the browser. For server-only operations (like using tokens), don't use the NEXT_PUBLIC_ prefix:

# Server-side only (never exposed to browser)
SANITY_API_TOKEN=your-secret-token

# Client-side accessible
NEXT_PUBLIC_SANITY_PROJECT_ID=abc123

Problem 3: Not Restarting Dev Server After changing .env files, you must restart your Next.js dev server. The variables are only loaded at startup.

Problem 4: Wrong .env File Make sure you're using the right file:

• .env.local - loaded in all environments (gitignored by default)
• .env.development - only in development
• .env.production - only in production builds

Quick Debugging Checklist

1. Check your variable names have the correct prefix (NEXT_PUBLIC_ or SANITY_STUDIO_)
2. Restart your dev server after any .env changes
3. Verify the values are loading: console.log(process.env.NEXT_PUBLIC_SANITY_PROJECT_ID)
4. Make sure your .env.local file is in the root of your Next.js project
5. Check that sensitive .env.local files are in .gitignore

Typical Setup for Next.js + Sanity

Here's what a standard .env.local file looks like for an embedded Studio:

# For Next.js client-side
NEXT_PUBLIC_SANITY_PROJECT_ID=abc123
NEXT_PUBLIC_SANITY_DATASET=production

# For embedded Sanity Studio
SANITY_STUDIO_API_PROJECT_ID=abc123
SANITY_STUDIO_API_DATASET=production

# For server-side API routes (no NEXT_PUBLIC!)
SANITY_API_READ_TOKEN=your-token-here

The key thing to remember: project IDs and dataset names aren't secret and will be exposed in your built application anyway, so using NEXT_PUBLIC_ for them is fine. But keep API tokens server-side only without the NEXT_PUBLIC_ prefix!