hasura/graphql-engine · error · MapFieldNamesError

Unknown fields found in object type {object_type_name}: {fie

Error message

Unknown fields found in object type {object_type_name}: {fields:?}

What it means

MapFieldNamesError::UnknownFieldsInObject is a strict-mode style error: after mapping all recognized fields of an argument object, one or more fields were left over that have no mapping in the object's type mapping. The planner lists the unmapped field names rather than silently ignoring them, to prevent silent data loss.

Source

Thrown at v3/crates/plan/src/query/arguments.rs:662

pub enum MapFieldNamesError {
    #[error("Value did not match array type, was expecting {expected_type}")]
    ExpectedAnArray {
        expected_type: QualifiedTypeReference,
    },
    #[error("Value did not match object type, was expecting {expected_type}")]
    ExpectedAnObject {
        expected_type: QualifiedTypeReference,
    },
    #[error("Type mappings not found for object type {object_type_name}")]
    TypeMappingsNotFound {
        object_type_name: Qualified<CustomTypeName>,
    },
    #[error("Field mapping {field_name} not found for object type {object_type_name}")]
    FieldMappingNotFound {
        object_type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
    },
    #[error("Unknown fields found in object type {object_type_name}: {fields:?}")]
    UnknownFieldsInObject {
        object_type_name: Qualified<CustomTypeName>,
        fields: Vec<String>,
    },
}

impl TraceableError for MapFieldNamesError {
    fn visibility(&self) -> ErrorVisibility {
        match self {
            Self::ExpectedAnArray { .. }
            | Self::ExpectedAnObject { .. }
            | Self::UnknownFieldsInObject { .. } => ErrorVisibility::User,
            Self::TypeMappingsNotFound { .. } | Self::FieldMappingNotFound { .. } => {
                ErrorVisibility::Internal
            }
        }
    }
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Remove the listed unknown fields from the argument object
2. Align the client payload with the current schema's field set for that object type
3. If the fields are legitimate, add them to the connector's field mappings / metadata
4. Add client-side validation (e.g. zod .strict()) to catch extra keys early

Example fix

// before
{ "where": { "id": 1, "debug": true } }   // "debug" unknown
// after
{ "where": { "id": 1 } }

let known: HashSet<_> = mapping.field_mappings.keys().cloned().collect();
let extra: Vec<_> = value.keys().filter(|k| !known.contains(*k)).collect();
assert!(extra.is_empty(), "unknown fields: {extra:?}");

const stripUnknown = <T extends object>(v: T, known: string[]) => Object.fromEntries(Object.entries(v).filter(([k]) => known.includes(k)));

Catch UnknownFieldsInObject and echo the fields list back for quick client-side fixes.

When it happens

Trigger: Sending extra fields in a nested argument object that are not declared in the type mapping's field_mappings — e.g. legacy fields removed from the schema, or client-side enrichment fields accidentally left in the payload.

Common situations: Client sending supersets of fields after schema pruning; version skew between old clients and new schemas; copy-pasted variable payloads with leftover keys; debug fields accidentally included.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Field mapping {field_name} not found for object type {object
• Field mapping not found for the field {field_name:} of type
• error from data source: {}
• Relationship '{name}' is either remote or not having 'relati
• {0}

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