facebook/relay · error

field has supported arg, but missing from the schema

Error message

field has supported arg, but missing from the schema

What it means

has_match_supported_arg first looks at a field's IR arguments for the @match supported argument, and when present expects the schema's field definition to declare the same argument (schema.field(...).arguments.named(...)). This expect fires when the argument appears in the compiled usage but is absent from the schema definition — the schema and the document disagree.

Source

Thrown at compiler/crates/relay-transforms/src/match_/hash_supported_argument.rs:128

}

impl HashSupportedArgumentTransform<'_> {
    /// Returns true iff the field is supplied with a `supported` arg and that
    /// arg has a type of `[string]` (potentially non-nullable somewhere).
    fn has_match_supported_arg(&self, field: &LinkedField) -> bool {
        if field
            .arguments
            .named(MATCH_CONSTANTS.supported_arg)
            .is_none()
        {
            return false;
        }
        let supported_arg_def = self
            .schema
            .field(field.definition.item)
            .arguments
            .named(MATCH_CONSTANTS.supported_arg)
            .expect("field has supported arg, but missing from the schema");

        if let TypeReference::List(item_type) = supported_arg_def.type_.nullable_type()
            && let TypeReference::Named(item_type_name) = item_type.nullable_type()
        {
            return self.schema.is_string(*item_type_name);
        }
        false
    }
}

#[derive(Debug, Error, serde::Serialize)]
#[serde(tag = "type")]
pub enum HashSupportedArgumentError {
    #[error(
        "Variables cannot be passed to the `supported` argument for data driven dependency fields, please use literal values like `\"ExampleValue\"`."
    )]
    NonStaticSupportedArg,
}

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Add the supported argument to the field's definition in the schema (e.g. viewer(filters: [MyEnum!]): User) so it matches the IR.
2. Regenerate/rebuild schema artifacts so the compiled program and schema come from the same run.
3. Clear stale build caches (relay build artifacts, persisted queries) and recompile.
4. Check for duplicate field definitions where only one variant declares the argument but the transform resolves the other.
5. Ensure the argument's type is a List of a Named type — the code immediately expects that shape via TypeReference::List/Named.

Example fix

// before (schema)
type Query { viewer: User }
// after (schema)
type Query {
  viewer(supportedLocales: [Language!]): User
}

function schemaDeclaresSupportedArg(schema, fieldDefinition, argName) {
  return Boolean(
    fieldDefinition?.arguments?.some(
      a => a.name === argName &&
      a.type.toString().match(/\[.+!?!?\]/) // List of a named type
    )
  );
}
// build/validate schema first:
// if (!schemaDeclaresSupportedArg(schema, schema.getQueryType().getFields().viewer, 'supportedLocales')) throw ...

function hasNamedListArg(fieldDef, argName) {
  const arg = fieldDef?.arguments?.find(a => a.name === argName);
  if (!arg) return false;
  return /\[\s*\w+\s*!?!?\s*\]/.test(String(arg.type));
}

try {
  program = applyMatchTransform(program);
} catch (e) {
  if (String(e.message).includes('missing from the schema')) {
    throw new Error(`Schema/document mismatch: declare the supported argument in the schema for field used with @match (source: ${e.message})`);
  }
  throw e;
}

When it happens

Trigger: Calling transform_linked_field on a field whose arguments contain the supported_arg while the schema definition of that field lacks it — typically after schema regeneration, a partial schema merge, or compiling against stale artifacts.

Common situations: Schema regenerated without the supported argument input field while cached compiled artifacts still reference it; codegen ran against an older schema; splitting/merging schema files dropped the argument definition; the argument is declared on a different field variant than the one resolved.

Related errors

• expected to find a supported argument as checked before
• Expected filters_arg to have been previously validated.
• Cannot have @module selections at multiple paths unless the
• Expect the module import inline fragment to have a type
• unexpected value for @defer if argument: {other:?}

AI-assisted analysis of facebook/relay@668b1b85e0 (2026-09-02). Data as JSON: /api/errors/09a2aaac94c5439e. Report an issue: GitHub.