{"record":{"id":"ed1cd4fd368db2bf","repo":"JuliusBrussee/caveman","slug":"caveman-agent-unknown-sandbox-mode-json-stringi","errorCode":null,"errorMessage":"caveman agent: unknown sandbox mode ${JSON.stringify(sandbox)}","messagePattern":"caveman agent: unknown sandbox mode (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/index.ts","lineNumber":107,"sourceCode":"  instructions: string | FileSource;\n  model: Auto | string | Model<Api>;\n  reasoning?: AgentDefinition[\"reasoning\"];\n  tools?: ToolDefinition[];\n  contexts?: ContextDefinition[];\n  memory?: MemoryDefinition;\n  output?: OutputDefinition;\n  sandbox?: AgentDefinition[\"sandbox\"];\n}): AgentDefinition {\n  if (!/^[a-z0-9][a-z0-9_-]{0,95}$/.test(options.id)) {\n    throw new Error(`caveman agent: invalid agent id ${JSON.stringify(options.id)}`);\n  }\n  const tools = Object.freeze([...(options.tools ?? [])]);\n  if (new Set(tools.map((item) => item.name)).size !== tools.length) {\n    throw new Error(\"caveman agent: duplicate tool name\");\n  }\n  const sandbox = options.sandbox ?? \"required\";\n  if (!SANDBOX_MODES.includes(sandbox)) {\n    throw new Error(`caveman agent: unknown sandbox mode ${JSON.stringify(sandbox)}`);\n  }\n  const reserved = tools.find((item) => item.name.startsWith(\"cave_\"));\n  if (reserved) {\n    throw new Error(\n      `caveman agent: tool prefix cave_ is reserved by framework (${reserved.name})`,\n    );\n  }\n  const definition: AgentDefinition = {\n    kind: \"agent\",\n    id: options.id,\n    instructions: options.instructions,\n    model: options.model,\n    reasoning: options.reasoning ?? \"low\",\n    tools,\n    contexts: Object.freeze([...(options.contexts ?? [])]),\n    sandbox,\n    ...(options.memory === undefined ? {} : { memory: options.memory }),\n    ...(options.output === undefined ? {} : { output: options.output }),","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/index.ts#L89-L125","documentation":"Thrown by the agent() builder (packages/agent/src/index.ts:107): the sandbox option is not one of the framework's sandbox modes (SANDBOX_MODES — 'required', 'host', and the contained default set). Sandbox defaults to 'required'; any other string is rejected.","triggerScenarios":"Calling agent({ sandbox: ... }) with a typo or unknown value such as 'optional', 'none', 'unsafe', 'docker', or passing the wrong type (number/boolean).","commonSituations":"Assuming a 'none'/'off' mode exists and passing it; typos like 'host' or 'RequireD'; copying config between framework versions where mode names changed; intending host mode for an interactive coding agent but misspelling 'host'.","solutions":["Use one of the documented SANDBOX_MODES values — 'required' (default containment), 'host' (explicit opt-in for tools needing real host access), or the other exported mode.","Omit sandbox entirely if you want the default ('required').","Type the option as AgentDefinition['sandbox'] so the compiler catches invalid literals before runtime."],"exampleFix":"// before\nagent({ sandbox: \"none\" as any, /* ... */ });\n\n// after\nagent({ sandbox: \"host\", /* ... */ }); // or omit sandbox for the 'required' default","handlingStrategy":"type-guard","validationCode":"const SANDBOX_MODES = [\"required\", \"host\"] as const; // keep in sync with the framework export\nfunction isSandboxMode(v: unknown): v is (typeof SANDBOX_MODES)[number] {\n  return typeof v === \"string\" && (SANDBOX_MODES as readonly string[]).includes(v);\n}\nconst sandbox = rawConfig.sandbox ?? \"required\";\nif (!isSandboxMode(sandbox)) throw new Error(`unknown sandbox mode ${String(rawConfig.sandbox)}`);","typeGuard":"function isSandboxMode(v: unknown): v is AgentDefinition[\"sandbox\"] {\n  return typeof v === \"string\" && /^[a-z]+$/.test(v) && [\"required\", \"host\"].includes(v);\n}","tryCatchPattern":null,"preventionTips":["Type the option as AgentDefinition['sandbox'] so invalid literals fail to compile.","Validate sandbox values parsed from YAML/JSON config before calling agent().","Remember 'host' is an explicit opt-in; there is no 'none'/'off' mode."],"tags":["validation","sandbox","configuration"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}