nikivdev/code · error

MAPLE_API_TOKEN is not configured

Error message

MAPLE_API_TOKEN is not configured

What it means

This error is raised by the public `inspect_trace` function when `parse_maple_read_config_from_env` returns no config, which happens when the MAPLE_API_TOKEN environment variable is unset or empty. The library refuses to proceed because it cannot authenticate to the Maple MCP endpoint to read trace data. It is a configuration gate, not a runtime failure.

Source

Thrown at src/codex_telemetry.rs:547

        endpoint: config.endpoint,
        token_source: config.token_source,
        tools_list_ok: true,
        tools_count: tools.len(),
        read_probe_ok: read_probe
            .as_ref()
            .ok()
            .and_then(maple_tool_result_error)
            .is_none(),
        read_probe_error: match read_probe {
            Ok(value) => maple_tool_result_error(&value),
            Err(error) => Some(error.to_string()),
        },
    })
}

pub fn inspect_trace(trace_id: &str, flush_first: bool) -> Result<CodexTraceInspectResult> {
    let Some(config) = parse_maple_read_config_from_env()? else {
        anyhow::bail!("MAPLE_API_TOKEN is not configured");
    };
    let flushed = if flush_first {
        let _ = flush(64);
        true
    } else {
        false
    };
    let result = maple_call_tool(
        &config,
        "inspect_trace",
        serde_json::json!({
            "trace_id": trace_id,
        }),
    );
    let (result, read_error) = match result {
        Ok(result) => (Some(result), None),
        Err(error) => (None, Some(error.to_string())),
    };

View on GitHub (pinned to a747e741ae)

Solutions

1. Export the token: `export MAPLE_API_TOKEN=<your-token>` in the shell running the tool.
2. In CI, add MAPLE_API_TOKEN to the job's environment/secrets mapping.
3. If using a .env file, ensure it is loaded before the process starts.
4. Verify with `echo ${MAPLE_API_TOKEN:+set}` that the variable is visible to the process.

Example fix

// before: fails because token is unset
inspect_trace("abc123", true)?;
// after
// $ export MAPLE_API_TOKEN=sk-...
inspect_trace("abc123", true)?;

fn ensure_maple_read_config() -> Result<(), String> {
    match std::env::var("MAPLE_API_TOKEN") {
        Ok(t) if !t.trim().is_empty() => Ok(()),
        _ => Err("MAPLE_API_TOKEN must be exported and non-empty before calling inspect_trace".into()),
    }
}

if let Err(e) = ensure_maple_read_config() {
    eprintln!("{e}; run: export MAPLE_API_TOKEN=<token>");
    std::process::exit(2);
}
let result = inspect_trace(trace_id, true)?;

When it happens

Trigger: Calling `inspect_trace` (directly or via `inspect_current_session_trace`) in an environment where MAPLE_API_TOKEN is not set, e.g. a fresh shell, a CI job without secrets, or running the binary via a service manager that does not inherit your shell env.

Common situations: Forgetting to `export MAPLE_API_TOKEN=...` before running the tool, secrets not injected in CI (missing env mapping in the workflow), dotenv file not loaded, or running under sudo/systemd which strips the environment.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• upgrade source repo not configured. Set FLOW_UPGRADE_REPO=ow
• No profile selected.
• expected [{}] to be a table in global flow config
• empty resolver command for {}
• device auth start failed: HTTP {}

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/9f868966516ac30e. Report an issue: GitHub.