hasura/graphql-engine · error · RelationshipError

Relationships with nested field paths are not supported yet.

Error message

Relationships with nested field paths are not supported yet.

What it means

A relationship mapping referenced a nested (dot/multi-segment) field path such as `author.profile.id`. Nested field paths are parsed but not yet implemented by the resolver, so they are rejected.

Source

Thrown at v3/crates/metadata-resolve/src/stages/object_relationships/error.rs:172

    },
    #[error("Relationship mappings from value expressions are not supported yet.")]
    ValueExpressionMappingsNotSupportedYet,
    #[error(
        "The field path provided in the {location:} of the relationship {relationship_name} on type {type_name} is empty"
    )]
    EmptyFieldPath {
        location: String,
        relationship_name: RelationshipName,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "Model fields cannot be used in command based relationship: {relationship_name:} on type {type_name:}"
    )]
    ModelFieldCannotBeUsedInCommandRelationship {
        relationship_name: RelationshipName,
        type_name: Qualified<CustomTypeName>,
    },
    #[error("Relationships with nested field paths are not supported yet.")]
    NestedFieldPathsNotSupportedYet,
    #[error("{0}")]
    CommandError(#[from] commands::CommandsError),
    #[error("{0}")]
    ModelError(#[from] models::ModelsError),
    #[error("{0}")]
    GraphqlError(#[from] graphql_config::GraphqlConfigError),
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Flatten the schema: promote the nested value to a top-level field on the source type and map that field instead
2. Create an intermediate type plus a chained relationship to traverse the two hops separately
3. Upgrade to a future version once nested field paths are implemented

Example fix

// before
field_mappings:
  - source: author.profile.id
    target: { model: authors, field: id }
// after
# add author_id as a top-level field on the source type
field_mappings:
  - source: author_id
    target: { model: authors, field: id }

const isNested = (p: string) => p.split('.').length > 1 || Array.isArray(p) && p.length > 1;
for (const m of rel.field_mappings ?? []) {
  if (isNested(m.source)) throw new Error('nested field paths are not supported yet');
}

try { await applyMetadata(md); } catch (e) { if (/nested field paths are not supported/.test(e.message)) { /* flatten or chain relationships */ } throw e; }

When it happens

Trigger: Using a dotted or multi-segment path anywhere a field path is expected in a relationship mapping.

Common situations: Trying to join through intermediate objects when the source type has object-typed fields; metadata authored assuming deep-path support.

Related errors

• Relationship mappings from value expressions are not support
• error while creating http client with TLS configuration %w
• cannot create migrations directory: %w
• the relationship '{relationship_name}' is defined more than
• the comparable relationship '{relationship_name}' for the op

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