hasura/graphql-engine · critical · StartupError

failed to build engine state - {0}

Error message

failed to build engine state - {0}

What it means

Variant StartupError::ReadSchema indicating the engine state (schema + metadata resolution) could not be built; the wrapped error carries the concrete cause. It is a user-visible startup error, so the fix is normally in configuration/metadata rather than code.

Source

Thrown at v3/crates/engine/src/types.rs:27

#[derive(Clone)] // Cheap to clone as heavy fields are wrapped in `Arc`
pub struct EngineState {
    pub expose_internal_errors: ExposeInternalErrors,
    pub http_context: HttpContext,
    pub graphql_state: Arc<gql::schema::Schema<GDS>>,
    pub resolved_metadata: Arc<metadata_resolve::Metadata>,
    pub jsonapi_catalog: Arc<jsonapi::Catalog>,
    pub auth_config: Arc<ResolvedAuthConfig>,
    pub graphql_websocket_server:
        Arc<graphql_ws::WebSocketServer<graphql_ws::NoOpWebSocketMetrics>>,
    pub auth_mode_header: String,
}

#[derive(thiserror::Error, Debug)]
#[allow(clippy::enum_variant_names)]
pub enum StartupError {
    #[error("could not read the auth config - {0}")]
    ReadAuth(anyhow::Error),
    #[error("failed to build engine state - {0}")]
    ReadSchema(anyhow::Error),
}

impl TraceableError for StartupError {
    fn visibility(&self) -> tracing_util::ErrorVisibility {
        ErrorVisibility::User
    }
}

/// The type of request being made to the engine
pub enum RequestType {
    Http,
    WebSocket,
}

impl RequestType {
    /// Convert the request type to a string
    /// Used to set the attribute on the "/graphql" span

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the wrapped inner error message for the root cause
2. Re-run metadata generation/validation and retry startup
3. Verify all referenced connectors are reachable and correctly configured
4. Align engine, CLI, and connector versions, then rebuild metadata

fn is_read_schema(e: &StartupError) -> bool { matches!(e, StartupError::ReadSchema(_)) }

Catch StartupError::ReadSchema, unwrap the inner anyhow chain with {:#} to print the full cause chain, and halt startup with a non-zero exit.

When it happens

Trigger: Engine state construction failing: unresolvable metadata, invalid subgraph schemas, connector configuration errors, or inconsistent auth/metadata combinations — any error during state building gets wrapped in this variant.

Common situations: Metadata referencing connectors that don't resolve, schema federation conflicts, version drift between CLI-generated metadata and engine, or partially deployed configuration files.

Related errors

• could not read metadata
• Serde error: {error}
• Condition {condition_hash} not found
• could not read auth config
• error building metadata

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