{"record":{"id":"a6f96d5658de5600","repo":"JuliusBrussee/caveman","slug":"cave-project-required","errorCode":"cave_project_required","errorMessage":"No project selected or accessible. Create/select a project before using Caveman agent tools.","messagePattern":"No project selected or accessible\\. Create/select a project before using Caveman agent tools\\.","errorType":"http","errorClass":"AgentMcpHTTPError","httpStatus":404,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":18434,"sourceCode":"      response.status,\n    );\n  }\n  return body;\n}\n\nasync function agentMcpProjectId(): Promise<string> {\n  const cfg = await config();\n  if (cfg.projectId) return cfg.projectId;\n  const projects = await agentMcpRequest(\"/api/v1/projects\");\n  const projectObject = projects && typeof projects === \"object\" && !Array.isArray(projects)\n    ? projects\n    : {};\n  const rows = Array.isArray(projectObject.data) ? projectObject.data : [];\n  const first = rows[0];\n  if (first && typeof first === \"object\" && !Array.isArray(first) && typeof first.id === \"string\" && first.id) {\n    return first.id;\n  }\n  throw new AgentMcpHTTPError(\n    \"No project selected or accessible. Create/select a project before using Caveman agent tools.\",\n    \"cave_project_required\",\n    404,\n  );\n}\n\nfunction recordAgentMcpToolCall(event: { tool: string; result: \"ok\" | \"error\"; durationMs: number }): void {\n  const state = telemetryState();\n  if (!telemetrySendable(state)) return;\n  emitTelemetryEvents([{\n    schema: \"cli/v1\",\n    anonymous_id: telemetryAnonymousId(state),\n    event: \"agent_tool_call\",\n    command: \"mcp\",\n    subcommand: event.tool,\n    cli_version: cliVersion(),\n    os: process.platform,\n    arch: process.arch,","sourceCodeStart":18416,"sourceCodeEnd":18452,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L18416-L18452","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Create a project: caveman project create <name> (or via the Caveman web UI) and select it.","Verify authentication: re-run caveman login / check the stored credentials so the projects list returns rows.","Check the API token scope — ensure it has access to a workspace containing at least one project.","Confirm CAVEMAN_HOME points at the intended profile with existing projects."],"exampleFix":"// before\nawait cavemanAgentRun(prompt); // throws cave_project_required\n// after\n// 1. caveman project create my-project\n// 2. caveman project use my-project\nawait cavemanAgentRun(prompt);","handlingStrategy":"validation","validationCode":"// ensure a project exists and is selected before agent tool use\nconst projects = await fetch(`${baseURL}/projects`, { headers: authHeaders() }).then(r => r.json());\nif (!Array.isArray(projects?.data) || projects.data.length === 0) {\n  throw new Error(\"No Caveman project available: run `caveman project create <name>` and `caveman project use <name>` first\");\n}","typeGuard":"function hasProject(listing: unknown): listing is { data: Array<{ id: string }> } {\n  const l = listing as { data?: unknown };\n  return Array.isArray(l?.data) && l.data.length > 0\n    && typeof (l.data[0] as { id?: unknown })?.id === \"string\";\n}","tryCatchPattern":"try {\n  await cavemanAgentRun(prompt);\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"No project selected\")) {\n    console.error(\"Create/select a project first: caveman project create && caveman project use\");\n  } else throw e;\n}","preventionTips":["Run `caveman login` and `caveman project create/use` as onboarding steps before agent tools","Verify token scope includes a workspace with projects","Check CAVEMAN_HOME points to the intended profile","Fail fast in scripts by listing projects before running agent commands"],"tags":["configuration","project","api"],"backgroundTag":"resource-not-found","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}