hasura/graphql-engine · error · ModelGraphqlError

unknown field {field_name:} in unique identifier defined for

Error message

unknown field {field_name:} in unique identifier defined for model {model_name:}

What it means

While generating the GraphQL API for a model, a field referenced in the model's unique identifier (used to build a node ID / object identity) does not exist on the model's type.

Source

Thrown at v3/crates/metadata-resolve/src/stages/models_graphql/error.rs:11

use open_dds::{models::ModelName, types::FieldName};

use crate::{
    Qualified,
    stages::{boolean_expressions, graphql_config, models},
    types::error::ContextualError,
};

#[derive(Debug, thiserror::Error)]
pub enum ModelGraphqlError {
    #[error("unknown field {field_name:} in unique identifier defined for model {model_name:}")]
    UnknownFieldInUniqueIdentifier {
        model_name: Qualified<ModelName>,
        field_name: FieldName,
    },
    #[error("duplicate field {field_name:} in unique identifier defined for model {model_name:}")]
    DuplicateFieldInUniqueIdentifier {
        model_name: Qualified<ModelName>,
        field_name: FieldName,
    },
    #[error(
        "filter input type name graphql configuration must be specified for model {model_name:} because aggregates are used with it"
    )]
    MissingFilterInputTypeNameGraphqlConfiguration { model_name: Qualified<ModelName> },

    #[error("{0}")]
    GraphqlConfigError(#[from] graphql_config::GraphqlConfigError),
    #[error("{0}")]
    ModelsError(#[from] models::ModelsError),

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add the missing field to the model type or correct its name
2. Remove the field from the unique identifier
3. If it's a nested field, use a top-level scalar field instead

Example fix

# before
type: user
unique_identifier: [id, email_address]  # field is 'email'
# after
unique_identifier: [id, email]

// every unique-identifier field must exist on the type
let field_names: HashSet<_> = model_type.fields.keys().cloned().collect();
for f in &model.unique_identifier {
    assert!(field_names.contains(f), "field {f} not on type");
}

When it happens

Trigger: Listing a field in the model's unique identifier that isn't a field of the model type, e.g. after renaming or removing a field.

Common situations: Renaming fields in the type without updating the unique identifier; copy-paste errors in metadata; referencing nested fields which are not allowed.

Related errors

• the return type used on the {count_type} aggregate ({return_
• the return type used on the {count_type} aggregate ({return_
• empty fields in apollo federation keys defined for the objec
• a source must be defined for model {model:} in order to use
• the boolean expression '{type_name}' has a GraphQL field nam

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