hasura/graphql-engine · error · ApolloError

unknown field {field_name:} in apollo federation keys define

Error message

unknown field {field_name:} in apollo federation keys defined for the object type {object_type:}

What it means

Thrown by the Apollo Federation metadata stage when a federation key defined for an object type references a field name that does not exist on that object type. Entity keys must consist of real fields so a subgraph can resolve entities by those keys, so the resolver validates each key field against the type's field set and fails on the first unknown one.

Source

Thrown at v3/crates/metadata-resolve/src/stages/apollo/mod.rs:38

    // To check if apollo federation entity keys are defined in object type but no model has
    // apollo_federation_entity_source set to true:
    //   - Throw an error if no model with apolloFederation.entitySource:true is found for the object type.
    for (object_type, model_name_list) in apollo_federation_entity_enabled_types {
        if model_name_list.is_none() {
            return Err(ApolloError::ApolloFederationEntitySourceNotDefined { object_type });
        }
    }
    Ok(())
}

#[derive(Debug, thiserror::Error)]
pub enum ApolloError {
    #[error("empty fields in apollo federation keys defined for the object type {object_type:}")]
    EmptyFieldsInApolloFederationConfigForObject {
        object_type: Qualified<CustomTypeName>,
    },

    #[error(
        "unknown field {field_name:} in apollo federation keys defined for the object type {object_type:}"
    )]
    UnknownFieldInApolloFederationKey {
        field_name: FieldName,
        object_type: Qualified<CustomTypeName>,
    },
    #[error(
        "empty keys in apollo federation configuration defined for the object type {object_type:}"
    )]
    EmptyKeysInApolloFederationConfigForObject {
        object_type: Qualified<CustomTypeName>,
    },
    #[error(
        "'apolloFederation.keys' for type {object_type:} found, but no model found with 'apolloFederation.entitySource: true' for type {object_type:}"
    )]
    ApolloFederationEntitySourceNotDefined {
        object_type: Qualified<CustomTypeName>,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the field set of the named object type and correct the key field name (spelling and casing must match exactly).
2. If the field was renamed, update the federation key to the new name.
3. If the key genuinely needs a field the type doesn't expose, add that field to the type first, or remove it from the key.

Example fix

# before
type: users
apolloFederation:
  keys:
    - [user_id]   # field does not exist
# after
type: users
apolloFederation:
  keys:
    - [id]        # actual field name

fn key_fields_exist(type_fields: &HashSet<String>, keys: &[Vec<String>]) -> bool {
    keys.iter().flatten().all(|f| type_fields.contains(f))
}

When it happens

Trigger: Configuring apolloFederation.keys: [[someField]] on a type where 'someField' is not among the type's fields — due to a typo, a renamed field, or a field that exists only on a different type.

Common situations: Renaming a model field without updating federation keys; typos in field names in hand-written metadata; copying a keys block from another type; keys referencing relationship/command fields that are not part of the object type's field set.

Related errors

• empty fields in apollo federation keys defined for the objec
• empty keys in apollo federation configuration defined for th
• Model {model_name:} is marked as an Apollo Federation entity
• 'apolloFederation.keys' for type {object_type:} found, but n
• model {model_name:} with arguments is unsupported as an Apol

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/a708592d1c4c688c. Report an issue: GitHub.