hasura/graphql-engine · error

error building metadata

Error message

error building metadata

What it means

Generic anyhow error returned by engine::resolve_metadata after metadata validation reports have already been printed to stderr via ariadne. The real diagnostic details are in the printed reports; this error exists only to propagate failure (and stop error printing from happening twice), so the message itself carries no detail.

Source

Thrown at v3/crates/engine/src/state.rs:42

    let auth_config =
        hasura_authn::parse_auth_config(raw_auth_config).map_err(StartupError::ReadAuth)?;
    let (resolved_auth_config, auth_warnings) =
        hasura_authn::resolve_auth_config(auth_config, flags.as_ref())?;

    let (resolved_metadata, warnings) =
        metadata_resolve::resolve(metadata, metadata_resolve_configuration).map_err(|error| {
            let reports = metadata_resolve::to_fancy_errors(
                opendd_metadata_json,
                &error,
                ariadne::Config::new(),
            );
            for report in reports {
                report
                    .eprint(ariadne::Source::from(opendd_metadata_json))
                    .unwrap();
            }
            // return empty error to stop printing twice
            anyhow::anyhow!("error building metadata")
        })?;

    print_warnings(auth_warnings);
    print_warnings(warnings);

    Ok((resolved_metadata, resolved_auth_config))
}

/// Build the engine state - include auth, metadata, and jsonapi context.
pub fn build_state(
    expose_internal_errors: ExposeInternalErrors,
    auth_config: hasura_authn::ResolvedAuthConfig,
    resolved_metadata: metadata_resolve::Metadata,
    auth_mode_header: String,
    ndc_response_size_limit: usize,
) -> Result<EngineState, anyhow::Error> {
    // Metadata
    let resolved_metadata = Arc::new(resolved_metadata);

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the ariadne validation reports printed just above this error — they contain the actual problem
2. Fix the reported metadata issues (types, names, relationships) in the source metadata
3. Regenerate metadata from your source schemas instead of hand-editing
4. Pin matching versions of engine/CLI/connector so metadata format matches

fn is_metadata_error(e: &anyhow::Error) -> bool { e.to_string().contains("error building metadata") }

Catch the anyhow error from resolve_metadata, log that detailed ariadne reports were already printed to stderr, and surface a concise 'metadata invalid' message to the operator.

When it happens

Trigger: Calling engine::resolve_metadata with an OpenDD metadata JSON that fails validation; the function renders each report against the metadata source and then returns this placeholder error via the ?-operator on the closure result.

Common situations: Invalid or malformed metadata documents, schema/argument type mismatches between subgraphs, stale metadata after upgrading engine or connector versions, or hand-edited metadata JSON.

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

• the field '{field_name}' is defined more than once in the co
• {message}
• error while parsing the endpoint :%w
• failed to get version from server: %w
• cannot read config from file/env: %w

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