Starting in API version 2026-10, the GraphQL Admin API returns an error when a query filters by a metafield that isn't set up for filtering, instead of silently returning incorrect results. This is a breaking change. It affects apps that filter resources by metafield on version 2026-10 or later, and you'll need to update affected queries before you upgrade.
What changed
In API version 2026-10 and later, the GraphQL Admin API checks metafield filters before it runs a query. If a query filters by a metafield that can't be used for filtering, the query returns an error explaining the problem instead of ignoring the invalid predicate and returning an incorrect result.
A metafield filter commonly fails when:
- The metafield doesn't have a definition.
- The metafield's definition isn't configured to allow filtering.
- The metafield's type doesn't support the filter or comparison you used.
Previously, invalid predicates in metafield filters were silently ignored, so a query with an invalid filter could return misleading results. Now the response tells you the filter is the problem, so you can correct it.
Who's affected
This change affects apps and integrations that filter by metafields in the GraphQL Admin API (for example, filtering products, orders, or customers by a metafield) on API version 2026-10 or later. Queries on version 2026-07 and earlier keep the previous behavior and aren't affected until you upgrade.
You're affected only when a query filters by a metafield that isn't valid for filtering. Queries that filter by metafields set up for filtering, using a supported comparison, behave exactly as before and return the same results.
Why this matters
Silently returning incorrect results made invalid metafield filters hard to catch: a mistyped or unsupported filter looked identical to a query that simply had different matches. Returning an error instead lets you find and fix these problems during development, rather than shipping a filter that quietly returns nothing in production.
Breaking changes and migrations
API version 2026-10 is scheduled for release on October 1, 2026. Once you make requests on 2026-10 or later, a query that filters by a metafield that isn't set up for filtering returns an error instead of an empty result.
To migrate:
- Find the queries in your app that filter by metafields in the GraphQL Admin API.
- For each one, confirm the metafield has a definition, the definition allows filtering, and the comparison you use is supported for that metafield's type.
- Update any filter that references a metafield that isn't set up for filtering.
- Test your queries against version 2026-10 and confirm they return results without an error.
If a metafield you rely on can't be filtered yet, keep those queries on version 2026-07 or earlier until you've updated your app, and set up the metafield definition for filtering before you upgrade.