{"record":{"id":"c6302b0616d2611c","repo":"hasura/graphql-engine","slug":"could-not-read-metadata","errorCode":null,"errorMessage":"could not read metadata","messagePattern":"could not read metadata","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"v3/crates/engine/bin/engine/main.rs","lineNumber":147,"sourceCode":"    tracing_util::shutdown_tracer();\n}\n\n#[allow(clippy::print_stdout)]\nasync fn start_engine(server: &ServerOptions) -> Result<(), StartupError> {\n    let metadata_resolve_configuration = metadata_resolve::configuration::Configuration {\n        unstable_features: resolve_unstable_features(&server.unstable_features),\n    };\n\n    let expose_internal_errors = if server.expose_internal_errors {\n        ExposeInternalErrors::Expose\n    } else {\n        ExposeInternalErrors::Censor\n    };\n\n    let raw_auth_config =\n        std::fs::read_to_string(&server.authn_config_path).expect(\"could not read auth config\");\n    let opendd_metadata_json =\n        std::fs::read_to_string(&server.metadata_path).expect(\"could not read metadata\");\n\n    let (resolved_metadata, auth_config) = engine::resolve_metadata(\n        &opendd_metadata_json,\n        &raw_auth_config,\n        &metadata_resolve_configuration,\n    )\n    .map_err(StartupError::ReadSchema)?;\n\n    let state = engine::build_state(\n        expose_internal_errors,\n        auth_config,\n        resolved_metadata,\n        server.auth_mode_header.clone(),\n        server.ndc_response_size_limit,\n    )\n    .map_err(StartupError::ReadSchema)?;\n\n    let mut app = get_base_routes(state.clone(), server.request_body_limit);","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/engine/bin/engine/main.rs#L129-L165","documentation":"Panic from expect() in the engine's main() when the metadata (OpenDD) JSON file cannot be read from disk. The engine requires the metadata document describing connectors and authentication to start, so an unreadable file aborts startup.","triggerScenarios":"Starting the engine with a metadata path that does not exist, is unreadable, is a directory, or contains non-UTF8 bytes (read_to_string requires valid UTF-8).","commonSituations":"Metadata file not generated or not copied into CI/deployment artifacts, path typos in launch scripts, non-UTF8 metadata produced by other tooling, or missing volume mounts.","solutions":["Confirm the metadata file exists at the exact path passed to the binary","Regenerate metadata via your build/federation step if it was never produced","Ensure the file is valid UTF-8 text (file <path>, iconv if needed)","Fix permissions or mount the file into the container"],"exampleFix":"// before\nlet opendd_metadata_json =\n    std::fs::read_to_string(&server.metadata_path).expect(\"could not read metadata\");\n\n// after\nlet opendd_metadata_json = std::fs::read_to_string(&server.metadata_path)\n    .with_context(|| format!(\"could not read metadata at {}\", server.metadata_path.display()))?;","handlingStrategy":"validation","validationCode":"let p = &server.metadata_path;\nassert!(p.is_file(), \"metadata file missing: {}\", p.display());\nlet bytes = std::fs::read(p)?;\nlet opendd_metadata_json = String::from_utf8(bytes)?;","typeGuard":null,"tryCatchPattern":"Convert the expect() into a Result with context (path + io error kind) so startup surfaces an actionable message.","preventionTips":["Generate metadata as a build artifact and validate in CI","Fail fast in Dockerfiles if the metadata file is absent","Keep metadata generation and engine startup in the same pipeline"],"tags":["metadata","filesystem","startup","utf8","rust"],"backgroundTag":"metadata-file-not-found","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}