Diagnosing Empty GROQ Query Results in Sanity Studio

Recognizable condition

You run a GROQ query in Sanity Vision, your custom frontend, or a CLI script and receive an empty array ([]) or null even though you know documents that should match the filter exist in the dataset.

Cause / diagnostic table

Possible cause	What to look for
Syntax error (missing parentheses, wrong attribute path)	Query fails silently and returns no rows; Vision may show a warning icon.
Schema type name mismatch	The _type value in the query does not exactly match the schema definition (case‑sensitive).
Language/locale filtering	Dataset uses a language field (e.g., _lang) and the query omits the locale condition, causing the default locale to return none.
Insufficient token permissions	The request uses a token that lacks read scope for the dataset or specific document IDs.
Recent schema change not yet loaded	After adding/removing fields, the Studio or CDN may still serve an outdated schema version.

Ordered verification checks

1. Inspect the query syntax

   Open Sanity Vision (https://<project-id>.sanity.studio/vision) and paste the query. Look for any red underline or warning tooltip. Fix obvious typos such as missing parentheses or incorrect field names (e.g., slug.current vs slug).

   *[_type == "article" && slug.current == "my-post"]

2. Confirm schema type name

   In the Studio, go to Schema Types and locate the type you are querying (e.g., article). Ensure the spelling and casing match exactly what you used in _type. If the type is defined as Article with a capital A, the query must use Article.

3. Check for language/locale filters

   If your dataset includes a language field (commonly _lang or a custom language string), the query must either:

   • Include an explicit locale condition: *[_type == "article" && (_lang == "en" || !defined(_lang))]
   • Or remove the locale restriction if you want all languages.

   Test both versions in Vision to see if results appear.

4. Validate token permissions

   Determine which token your application or CLI uses. Run:

   sanity auth list

   Look for the token’s scopes; it must contain read. If you are using a custom token, verify it in the project settings under API → Tokens. As a quick test, replace the token with a known read-enabled token (e.g., the developer token) and re‑run the query.

5. Force schema/CDN refresh

   If you recently edited the schema, restart the local Studio:

   sanity start

   Or, in the Sanity dashboard, navigate to Settings → API → CDN and click Purge cache. Then re‑run the query in Vision.

Fixes tied to findings

• Syntax: Correct the query and save it in your codebase.
• Schema mismatch: Align the query’s _type value with the schema definition (or rename the schema type if appropriate).
• Locale: Add the needed locale condition or adjust your dataset’s language strategy.
• Token: Generate a new token with read scope or update the existing token’s permissions.
• Schema cache: Restart Studio or purge CDN cache to load the latest schema.

Escalation criteria

If after completing all five checks the query still returns empty results:

1. Verify that the documents are actually published (not only drafts) by toggling the ?includeDrafts=true parameter in Vision.
2. Check the dataset’s _id values directly via the Documents list to ensure the expected IDs exist.
3. Contact Sanity support with the exact query, token scopes (redacted), and a screenshot of Vision showing the empty result, noting the dataset name and project ID.

These steps help distinguish between a genuine data absence and a configuration or permission issue, allowing you to resolve the problem or provide the support team with the necessary diagnostics.