JuliusBrussee/caveman · error · Error

cave_sandbox_credential_env_not_allowlisted

cave_sandbox_credential_env_not_allowlisted

Error message

cave_sandbox_credential_env_not_allowlisted

What it means

validateSandboxCredentialEnv rejects any environment variable name requested for sandbox credential injection that is not on the sandbox credential allowlist (SANDBOX_CREDENTIAL_ENV_TO_CAPABILITY). The name is deliberately omitted from the error to avoid leaking secret-identifying names.

Solutions

1. Use only allowlisted sandbox credential env names (e.g. standard provider API key vars).
2. Fix typos in the profile's credential env names.
3. Check library docs/changelog for the current set of supported credential env vars.
4. Extend via the library's official mechanism if a new credential must be supported, not by bypassing validation.

Example fix

// before
profile.credentialEnv = ["MY_OPENAI_KEY"];
// after
profile.credentialEnv = ["OPENAI_API_KEY"]; // allowlisted name

const ALLOWED = [...SANDBOX_CREDENTIAL_ENV_ALLOWLIST];
const bad = profile.credentialEnv.filter((n: string) => !ALLOWED.includes(n));
if (bad.length) console.error("not allowlisted:", bad); // before loading profile

const isAllowlistedCredentialEnv =
  (name: string): boolean => SANDBOX_CREDENTIAL_ENV_TO_CAPABILITY.has(name);

try {
  const profile = loadEvalSandboxProfile(p);
} catch (e) {
  if (e.message === "cave_sandbox_credential_env_not_allowlisted") {
    console.error("Profile uses a non-allowlisted credential env name (name withheld by design)");
  } else throw e;
}

When it happens

Trigger: A sandbox/eval profile (loadEvalSandboxProfile) or buildSandboxToolEnv requests a credential env var name not present in SANDBOX_CREDENTIAL_ENV_TO_CAPABILITY; a typo'd or profile-controlled name is passed to the credential-env validation.

Common situations: Typo in an env var name in a sandbox profile config; renaming a provider credential env var after a library update; custom profiles referencing vendor-specific secret names that are not allowlisted.

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

• cave_sandbox_credential_capability_ambiguous
• cave_host_sandbox_nested_under_required
• cave_live_eval_sandbox_profile_escapes_root
• cave_sandbox_child_process_containment_unavailable
• cave_sandbox_conformance_failed

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

Appendix: source

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

  "PATH",
  "PWD",
  "SHELL",
  "DYLD_INSERT_LIBRARIES",
]);

export function validateSandboxCredentialEnv(names: readonly string[]): void {
  const capabilities = new Set<SandboxCredentialCapability>();
  for (const name of names) {
    const denied = typeof name === "string" &&
      (SANDBOX_CREDENTIAL_DENY_NAMES.has(name) ||
        SANDBOX_CREDENTIAL_DENY_PREFIXES.some((prefix) => name.startsWith(prefix)));
    const capability = denied || typeof name !== "string"
      ? undefined
      : SANDBOX_CREDENTIAL_ENV_TO_CAPABILITY.get(name);
    if (capability === undefined) {
      // Keep profile-controlled names out of errors. This is a policy result,
      // not a diagnostic surface, and the name may itself identify a secret.
      throw new Error("cave_sandbox_credential_env_not_allowlisted");
    }
    capabilities.add(capability);
  }
  if (capabilities.size > 1) {
    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",

View on GitHub (pinned to 3ee70a1026)