JuliusBrussee/caveman · error · Error

cave_sandbox_credential_missing

cave_sandbox_credential_missing

Error message

cave_sandbox_credential_missing

What it means

buildSandboxToolEnv injects the validated credential env vars into the child sandbox environment by reading them from process.env; if one is undefined the required live credential is absent and the build aborts.

Solutions

  1. Export the required provider credential env var before running the agent.
  2. Load your .env file (e.g. dotenv) at process start.
  3. Verify with `printenv ANTHROPIC_API_KEY` (or the relevant name) that it is set in the launching shell.
  4. Ensure the same user/shell environment is used as where the profile was validated.

Example fix

// before
node agent.mjs // OPENAI_API_KEY unset
// after
OPENAI_API_KEY=sk-... node agent.mjs
Defensive patterns

Strategy: validation

Validate before calling

const missing = names.filter((n: string) => process.env[n] === undefined);
if (missing.length) throw new Error(`missing credentials: ${missing.join(",")}`); // before spawning sandbox

Try / catch

try {
  const env = buildSandboxToolEnv(names);
} catch (e) {
  if (e.message === "cave_sandbox_credential_missing") {
    console.error("Required provider credential env var is not set in this shell");
  } else throw e;
}

Prevention

When it happens

Trigger: A sandbox profile allowlists a credential env var name but the corresponding variable is not set in the parent process environment when the sandboxed tool child is spawned.

Common situations: Running locally without exporting the provider API key that CI has; .env file not loaded before spawning the sandbox; a renamed credential env var; shell environment stripped (e.g. sudo, systemd, container with minimal env).

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

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/d5a6b0ea50ebed32. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/runtime.ts:624

    throw new Error("cave_sandbox_credential_capability_ambiguous");
  }
}

/** Build the complete environment for an isolated tool child. No spread of
 * `process.env`: only deterministic runtime baseline plus an exact provider
 * capability selected by the validated live profile. */
export function buildSandboxToolEnv(names: readonly string[] = []): NodeJS.ProcessEnv {
  validateSandboxCredentialEnv(names);
  const env: NodeJS.ProcessEnv = {
    LANG: process.env.LANG ?? "C",
    LC_ALL: process.env.LC_ALL ?? "C",
    PATH: process.env.PATH ?? "",
    TZ: process.env.TZ ?? "UTC",
    CAVE_EVAL_FIXTURE: "1",
  };
  for (const name of names) {
    const value = process.env[name];
    if (value === undefined) throw new Error("cave_sandbox_credential_missing");
    env[name] = value;
  }
  return env;
}

interface InternalRunOptions extends RunOptions {
  lockedBuild?: CaveBuildLock;
  candidatePlan?: CavePlan;
  /**
   * Resolved once per root run and handed to descendants so a nested agent
   * neither re-probes the gateway nor disagrees with its parent about whether
   * this run is optimized or observe-only.
   */
  caveRoute?: ResolvedCaveRoute;
}

export type ResolvedCaveRoute = {
  readonly useGateway: boolean;

View on GitHub (pinned to 3ee70a1026)