Sanity query returns undefined in Next.js App Router despite correct setup

This is almost certainly a perspective issue related to a recent breaking change in Sanity's API! You're likely querying for documents that only exist as drafts, but your client is using the default published perspective which filters them out.

The Problem

As of API version 2025-02-19, the default perspective changed from raw to published. This means:

• Your Studio shows documents (including drafts)
• But cmsClient.fetch() and getDocument() only return published documents by default
• If your documents haven't been published yet, they only exist as drafts (with IDs like drafts.d13c0b40-b3e1-443a-a21f-a6bdbe128e6e)
• The published perspective filters these out, returning undefined

The Fix

Add the perspective parameter to your client configuration:

import { createClient } from 'next-sanity'

export const cmsClient = createClient({
  projectId: 'your-project-id',
  dataset: 'your-dataset',
  apiVersion: '2025-02-19',
  useCdn: false, // Disable CDN for draft content
  perspective: 'previewDrafts', // This will show drafts!
})

The available perspectives are:

• published (default) - Only published documents, no drafts
• previewDrafts - Prioritizes drafts over published (perfect for dev/preview)
• raw - Returns everything including both drafts and published

Debugging Steps

1. Check if your document is published: In Studio, if you see a "Publish" button, it's only a draft. Click it to publish.

2. Try querying explicitly for drafts:

const posts = await cmsClient.fetch(`*[_type=="bannerDe" || _id in path("drafts.**")]`)

1. Check the actual document ID: Your document might actually be drafts.d13c0b40-b3e1-443a-a21f-a6bdbe128e6e (note the drafts. prefix)

2. Use environment-specific perspectives:

export const cmsClient = createClient({
  // ... other config
  perspective: process.env.NODE_ENV === 'development' ? 'previewDrafts' : 'published',
})

This perspective change catches a lot of people, so you're definitely not alone! The fix is usually just adding that one perspective parameter to your client config.