JuliusBrussee/caveman · error · AgentMcpHTTPError

cave_project_required

cave_project_required

Error message

No project selected or accessible. Create/select a project before using Caveman agent tools.

What it means

Thrown by agentMcpProjectId() when no Caveman project exists or is accessible for the current credentials, so the agent MCP tools cannot determine which project to operate on. The client lists projects, takes the first row, and throws this 404-coded AgentMcpHTTPError when the list is empty or malformed. Any Caveman agent tool that resolves a project id will surface this before doing work.

Solutions

1. Create a project: caveman project create <name> (or via the Caveman web UI) and select it.
2. Verify authentication: re-run caveman login / check the stored credentials so the projects list returns rows.
3. Check the API token scope — ensure it has access to a workspace containing at least one project.
4. Confirm CAVEMAN_HOME points at the intended profile with existing projects.

Example fix

// before
await cavemanAgentRun(prompt); // throws cave_project_required
// after
// 1. caveman project create my-project
// 2. caveman project use my-project
await cavemanAgentRun(prompt);

// ensure a project exists and is selected before agent tool use
const projects = await fetch(`${baseURL}/projects`, { headers: authHeaders() }).then(r => r.json());
if (!Array.isArray(projects?.data) || projects.data.length === 0) {
  throw new Error("No Caveman project available: run `caveman project create <name>` and `caveman project use <name>` first");
}

function hasProject(listing: unknown): listing is { data: Array<{ id: string }> } {
  const l = listing as { data?: unknown };
  return Array.isArray(l?.data) && l.data.length > 0
    && typeof (l.data[0] as { id?: unknown })?.id === "string";
}

try {
  await cavemanAgentRun(prompt);
} catch (e) {
  if (e instanceof Error && e.message.includes("No project selected")) {
    console.error("Create/select a project first: caveman project create && caveman project use");
  } else throw e;
}

When it happens

Trigger: GET projects list returns data: [] (no projects), or the first row is not an object with a non-empty string id; occurs before any agent tool call that requires a project context.

Common situations: Fresh Caveman account/workspace with no project created, API token scoped to a workspace without projects, token revoked/expired so the list endpoint returns an empty set, or switching CAVEMAN_HOME to a fresh unauthenticated state.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• aes cipher
• apiKey, baseURL, and agent are required
• ASGI context resolver or request bounds are invalid
• AutoGen tools and workbench are mutually exclusive
• awssig: signer requires region and service

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

Appendix: source

Thrown at packages/cli/src/index.ts:18434

      response.status,
    );
  }
  return body;
}

async function agentMcpProjectId(): Promise<string> {
  const cfg = await config();
  if (cfg.projectId) return cfg.projectId;
  const projects = await agentMcpRequest("/api/v1/projects");
  const projectObject = projects && typeof projects === "object" && !Array.isArray(projects)
    ? projects
    : {};
  const rows = Array.isArray(projectObject.data) ? projectObject.data : [];
  const first = rows[0];
  if (first && typeof first === "object" && !Array.isArray(first) && typeof first.id === "string" && first.id) {
    return first.id;
  }
  throw new AgentMcpHTTPError(
    "No project selected or accessible. Create/select a project before using Caveman agent tools.",
    "cave_project_required",
    404,
  );
}

function recordAgentMcpToolCall(event: { tool: string; result: "ok" | "error"; durationMs: number }): void {
  const state = telemetryState();
  if (!telemetrySendable(state)) return;
  emitTelemetryEvents([{
    schema: "cli/v1",
    anonymous_id: telemetryAnonymousId(state),
    event: "agent_tool_call",
    command: "mcp",
    subcommand: event.tool,
    cli_version: cliVersion(),
    os: process.platform,
    arch: process.arch,

View on GitHub (pinned to 3ee70a1026)