hasura/graphql-engine · critical

could not read auth config

Error message

could not read auth config

What it means

Thrown by the engine binary's main() when std::fs::read_to_string fails on the authn config file path provided via CLI/server options. It is an expect() panic in the CLI wrapper, meaning the server cannot start without a readable authentication configuration file.

Source

Thrown at v3/crates/engine/bin/engine/main.rs:145

    }

    tracing_util::shutdown_tracer();
}

#[allow(clippy::print_stdout)]
async fn start_engine(server: &ServerOptions) -> Result<(), StartupError> {
    let metadata_resolve_configuration = metadata_resolve::configuration::Configuration {
        unstable_features: resolve_unstable_features(&server.unstable_features),
    };

    let expose_internal_errors = if server.expose_internal_errors {
        ExposeInternalErrors::Expose
    } else {
        ExposeInternalErrors::Censor
    };

    let raw_auth_config =
        std::fs::read_to_string(&server.authn_config_path).expect("could not read auth config");
    let opendd_metadata_json =
        std::fs::read_to_string(&server.metadata_path).expect("could not read metadata");

    let (resolved_metadata, auth_config) = engine::resolve_metadata(
        &opendd_metadata_json,
        &raw_auth_config,
        &metadata_resolve_configuration,
    )
    .map_err(StartupError::ReadSchema)?;

    let state = engine::build_state(
        expose_internal_errors,
        auth_config,
        resolved_metadata,
        server.auth_mode_header.clone(),
        server.ndc_response_size_limit,
    )
    .map_err(StartupError::ReadSchema)?;

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the path exists and is readable: ls -l <path> and cat it
2. Use an absolute path or resolve it relative to a known root before passing it to the server
3. If running in Docker/k8s, confirm the file is mounted/copied into the image at the expected location
4. Check file permissions (chmod +r) for the user running the engine

Example fix

// before
let raw_auth_config =
    std::fs::read_to_string(&server.authn_config_path).expect("could not read auth config");

// after (graceful startup error)
let raw_auth_config = std::fs::read_to_string(&server.authn_config_path)
    .map_err(|e| StartupError::ReadAuth(e.into()))?;

let p = &server.authn_config_path;
if !p.is_file() { eprintln!("auth config not found: {}", p.display()); std::process::exit(1); }
if let Err(e) = std::fs::metadata(p) { eprintln!("cannot stat auth config: {e}"); std::process::exit(1); }

Match on io::ErrorKind (NotFound, PermissionDenied) and print the path and OS error, then exit with a clear startup diagnostic instead of panicking.

When it happens

Trigger: Running the engine binary with --authn-config-path (or equivalent server option) pointing to a nonexistent file, a file without read permission, or a directory; or the path being relative to a different working directory.

Common situations: Wrong or misspelled path in container/deployment args, missing file in a Docker image, running from a different cwd so a relative path no longer resolves, or restrictive file permissions on secrets.

Related errors

• could not read the auth config - {0}
• could not read metadata
• error in writing config: %w
• read file: %w
• write file: %w

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