JuliusBrussee/caveman · error · Error

cave_tool_sandbox_entry_required

cave_tool_sandbox_entry_required

Error message

cave_tool_sandbox_entry_required: sandboxed tools need entryPath

What it means

prepareHarnessToolSandbox requires an entryPath when the agent definition's sandbox mode demands one (requiresSandboxEntry given sandboxRequired). Sandboxed tools must know which entry module to stage and execute.

Solutions

1. Pass entryPath pointing to the tool's entry module in the run/sandbox options.
2. Set definition.sandbox to a mode that doesn't require an entry if sandboxing isn't needed.
3. Fix the config so the entry path is resolved relative to the correct rootDir.
4. Check requiresSandboxEntry to understand when entryPath is mandatory.

Example fix

// before
await sandbox(definition, { rootDir: "/app" });
// after
await sandbox(definition, { rootDir: "/app", entryPath: "/app/tools/main.ts" });

if (definition.sandbox === "required" && options.entryPath === undefined) {
  throw new Error("sandboxed tools need entryPath");
}

const needsEntryPath = (d: AgentDefinition, o: { entryPath?: string }): boolean =>
  o.entryPath === undefined && d.sandbox === "required";

try {
  const sbx = await sandbox(definition, options);
} catch (e) {
  if (e.message.startsWith("cave_tool_sandbox_entry_required")) {
    console.error("Provide options.entryPath for sandboxed tool definitions");
  } else throw e;
}

When it happens

Trigger: Calling sandbox() (prepareHarnessToolSandbox) with options.entryPath undefined while the definition requires a sandbox entry (definition.sandbox === 'required' or executionContext.sandboxRequired).

Common situations: Forgetting to pass entryPath in run options after enabling sandbox: 'required'; renaming/moving the entry file so config loses the path; examples/docs updated to require entryPath after a version change.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Provide the native server identity and negotiated MCP…
• aes cipher
• apiKey, baseURL, and agent are required
• artifact_id is required
• ASGI context resolver or request bounds are invalid

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

Appendix: source

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

/** Package-internal harness bridge. Not exported from package entry point. */
export interface HarnessToolSandbox {
  readonly stagingRoot?: string;
  readonly entryPath?: string;
  readonly sourceFiles: readonly string[];
  readonly executionContext: InternalExecutionContext;
  dispose(): Promise<void>;
}

/** Package-internal harness bridge. Stages one immutable source graph. */
export async function prepareHarnessToolSandbox(
  definition: AgentDefinition,
  options: Pick<RunOptions, "rootDir" | "entryPath">,
): Promise<HarnessToolSandbox> {
  const executionContext = rootExecutionContext(definition);
  if (options.entryPath === undefined &&
      requiresSandboxEntry(definition, executionContext.sandboxRequired)) {
    throw new Error(
      "cave_tool_sandbox_entry_required: sandboxed tools need entryPath",
    );
  }
  if (options.entryPath === undefined) {
    return {
      sourceFiles: Object.freeze([]),
      executionContext,
      async dispose() {},
    };
  }
  const rootDir = options.rootDir ?? process.cwd();
  const requested = resolve(rootDir, options.entryPath);
  const snapshot = await stageSandboxSourceGraph(
    rootDir,
    requested,
    dirname(fileURLToPath(import.meta.url)),
  );
  return {

View on GitHub (pinned to 3ee70a1026)