{"record":{"id":"5726738d3dca2a64","repo":"hasura/graphql-engine","slug":"failed-to-build-engine-state-0","errorCode":null,"errorMessage":"failed to build engine state - {0}","messagePattern":"failed to build engine state - (.+?)","errorType":"exception","errorClass":"StartupError","httpStatus":null,"severity":"critical","filePath":"v3/crates/engine/src/types.rs","lineNumber":27,"sourceCode":"#[derive(Clone)] // Cheap to clone as heavy fields are wrapped in `Arc`\npub struct EngineState {\n    pub expose_internal_errors: ExposeInternalErrors,\n    pub http_context: HttpContext,\n    pub graphql_state: Arc<gql::schema::Schema<GDS>>,\n    pub resolved_metadata: Arc<metadata_resolve::Metadata>,\n    pub jsonapi_catalog: Arc<jsonapi::Catalog>,\n    pub auth_config: Arc<ResolvedAuthConfig>,\n    pub graphql_websocket_server:\n        Arc<graphql_ws::WebSocketServer<graphql_ws::NoOpWebSocketMetrics>>,\n    pub auth_mode_header: String,\n}\n\n#[derive(thiserror::Error, Debug)]\n#[allow(clippy::enum_variant_names)]\npub enum StartupError {\n    #[error(\"could not read the auth config - {0}\")]\n    ReadAuth(anyhow::Error),\n    #[error(\"failed to build engine state - {0}\")]\n    ReadSchema(anyhow::Error),\n}\n\nimpl TraceableError for StartupError {\n    fn visibility(&self) -> tracing_util::ErrorVisibility {\n        ErrorVisibility::User\n    }\n}\n\n/// The type of request being made to the engine\npub enum RequestType {\n    Http,\n    WebSocket,\n}\n\nimpl RequestType {\n    /// Convert the request type to a string\n    /// Used to set the attribute on the \"/graphql\" span","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/engine/src/types.rs#L9-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":"Metadata referencing connectors that don't resolve, schema federation conflicts, version drift between CLI-generated metadata and engine, or partially deployed configuration files.","solutions":["Inspect the wrapped inner error message for the root cause","Re-run metadata generation/validation and retry startup","Verify all referenced connectors are reachable and correctly configured","Align engine, CLI, and connector versions, then rebuild metadata"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"fn is_read_schema(e: &StartupError) -> bool { matches!(e, StartupError::ReadSchema(_)) }","tryCatchPattern":"Catch StartupError::ReadSchema, unwrap the inner anyhow chain with {:#} to print the full cause chain, and halt startup with a non-zero exit.","preventionTips":["Pre-validate metadata + connector config before launch","Keep engine, CLI, and connector versions in lockstep","Add smoke-test startup in CI/deploy pre-checks"],"tags":["startup","metadata","schema","rust"],"backgroundTag":"engine-startup-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}