{"record":{"id":"832a61a58dd803f0","repo":"xai-org/grok-build","slug":"headless-mode-requires-a-grok-com-session-run-gr","errorCode":null,"errorMessage":"Headless mode requires a grok.com session. Run `grok login` to sign in, or use `grok agent stdio` for API-key access.","messagePattern":"Headless mode requires a grok\\.com session\\. Run `grok login` to sign in, or use `grok agent stdio` for API-key access\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-shell/src/agent/app.rs","lineNumber":365,"sourceCode":"    let (mut auth, did_browser_flow) = if reauthenticate {\n        let auth_manager = Arc::new(AuthManager::new(&grok_home::grok_home(), ctx.clone()));\n        run_auth_flow(\n            &auth_manager,\n            ctx,\n            true,\n            None,\n            None,\n            None,\n            crate::auth::LoginTransportOverride::None,\n        )\n        .await?\n    } else {\n        let auth_manager = Arc::new(AuthManager::new(&grok_home::grok_home(), ctx.clone()));\n        if crate::agent::auth_method::has_xai_api_key_env()\n            && ctx.auth_provider_command.is_none()\n            && crate::auth::try_ensure_fresh_auth(ctx).await.is_none()\n        {\n            anyhow::bail!(\"{HEADLESS_NO_SESSION}\");\n        }\n        run_auth_flow(\n            &auth_manager,\n            ctx,\n            false,\n            None,\n            None,\n            None,\n            crate::auth::LoginTransportOverride::None,\n        )\n        .await?\n    };\n    if auth.user_id.is_empty() || auth.email.is_none() {\n        auth = Arc::new(agent_config.create_auth_manager())\n            .update(auth.clone())\n            .await?;\n    }\n    let auth_for_prefetch = auth.clone();","sourceCodeStart":347,"sourceCodeEnd":383,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-shell/src/agent/app.rs#L347-L383","documentation":"run_headless requires an authenticated grok.com session. Before starting headless mode, if an XAI API key env var is present and no auth-provider command is set, the code tries try_ensure_fresh_auth; if that returns None (no valid/fresh stored credentials), it bails with HEADLESS_NO_SESSION telling the user to run `grok login` or use `grok agent stdio` with an API key.","triggerScenarios":"Running headless mode with no stored grok.com session credentials: try_ensure_fresh_auth(ctx) returned None while has_xai_api_key_env() was true and ctx.auth_provider_command was None.","commonSituations":"Fresh machine or CI container where `grok login` was never run; expired/revoked session token; running headless in an environment without the stored auth state directory; user assumed the API key env var alone was enough for headless relay usage.","solutions":["Run `grok login` interactively to establish the grok.com session, then retry headless mode.","Use `grok agent stdio` instead, which supports API-key access without a grok.com session.","Ensure the auth state (grok home directory) is mounted/copied into CI or container environments.","Re-authenticate if the stored session expired (credentials exist but are stale)."],"exampleFix":"// before (CI script)\ngrok agent --headless ...\n// after\ngrok login  # once, interactively, to seed credentials\ngrok agent --headless ...\n# or, without a session:\ngrok agent stdio  # API-key access","handlingStrategy":"validation","validationCode":"// before invoking headless mode, check a session exists\nfn headless_ready() -> bool {\n    grok_home::has_session_credentials() // stored grok.com auth present\n}","typeGuard":null,"tryCatchPattern":"match app::run_headless(ctx).await {\n    Err(e) if e.to_string().contains(\"requires a grok.com session\") => {\n        eprintln!(\"No session. Run `grok login` first, or use `grok agent stdio`.\");\n        std::process::exit(2);\n    }\n    other => other,\n}","preventionTips":["Run `grok login` before scripted/headless usage on any new machine or container","Persist/mount the grok home credentials directory in CI images","Use `grok agent stdio` for API-key-only environments","Handle the error message explicitly in automation to print actionable guidance"],"tags":["authentication","headless","session","cli"],"backgroundTag":"missing-auth-session","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}