---
title: Invalid metafield queries now return errors in the GraphQL Admin API - Shopify developer changelog
description: Shopify’s developer changelog documents all changes to Shopify’s platform. Find the latest news and learn about new platform opportunities.
source_url:
  html: https://shopify.dev/changelog/invalid-metafield-queries-now-return-errors-in-the-graphql-admin-api
  md: https://shopify.dev/changelog/invalid-metafield-queries-now-return-errors-in-the-graphql-admin-api.md
---

# Invalid metafield queries now return errors in the GraphQL Admin API

DateJuly 24, 2026

Version[2026-10](https://shopify.dev/changelog?api_version=2026-10)

Flags[Breaking API Change](https://shopify.dev/changelog?filter=breaking-api-change)[Action required](https://shopify.dev/changelog?action_required=true)

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)[Metafields and metaobjects](https://shopify.dev/changelog?api_type=metafields-metaobjects)

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:

1. Find the queries in your app that filter by metafields in the GraphQL Admin API.
2. For each one, confirm the metafield has a definition, the definition [allows filtering](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#admin-filterable), and the [comparison you use](https://shopify.dev/docs/apps/build/metafields/query-using-metafields) is supported for that metafield's type.
3. Update any filter that references a metafield that isn't set up for filtering.
4. 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.