{"record":{"id":"d2e0f7f79a0bad97","repo":"JuliusBrussee/caveman","slug":"cave-request-failed","errorCode":"cave_request_failed","errorMessage":"Caveman API request failed (${response.status}).","messagePattern":"Caveman API request failed \\((.+?)\\)\\.","errorType":"error_code","errorClass":"AgentMcpHTTPError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":18409,"sourceCode":"    response = await fetch(`${cfg.baseURL}${path}`, request);\n  } catch (error) {\n    const timedOut = error instanceof Error && error.name === \"TimeoutError\";\n    throw new AgentMcpHTTPError(\n      timedOut\n        ? `Caveman API request timed out after ${agentMcpTimeoutMS()}ms.`\n        : error instanceof Error\n          ? error.message\n          : \"Caveman API request failed.\",\n      timedOut ? \"cave_agent_tool_timeout\" : \"cave_network_error\",\n    );\n  }\n  const body = await response.json().catch(() => ({})) as JSONObject;\n  if (!response.ok) {\n    const envelope = body.error && typeof body.error === \"object\" && !Array.isArray(body.error)\n      ? body.error as Record<string, unknown>\n      : {};\n    const flatCode = typeof body.error === \"string\" ? body.error : undefined;\n    throw new AgentMcpHTTPError(\n      typeof envelope.message === \"string\"\n        ? envelope.message\n        : typeof body.message === \"string\"\n          ? body.message\n          : `Caveman API request failed (${response.status}).`,\n      typeof envelope.code === \"string\" ? envelope.code : flatCode ?? \"cave_request_failed\",\n      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","sourceCodeStart":18391,"sourceCodeEnd":18427,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L18391-L18427","documentation":"Thrown by agentMcpRequest() after receiving an HTTP response with a non-ok status when the response body carries no usable error message or code. The client first tries to surface the API's structured error envelope (body.error.message or body.message) and envelope code; if none is a string it falls back to this generic message with code cave_request_failed. It represents a real HTTP-level failure of a Caveman API call whose server-side detail was lost.","triggerScenarios":"Any Caveman API request returning response.ok === false (4xx/5xx) where the parsed JSON body has neither body.error.message, body.message (strings) nor body.error/envelope.code to report.","commonSituations":"Gateway returning an HTML/plain-text error page (e.g. 502 from a reverse proxy) that fails JSON parse to {}, hitting a wrong path that yields an opaque 404, or an older gateway version not emitting the error envelope.","solutions":["Log/inspect response.status and the raw response body to identify the real server error.","Check the gateway version matches the CLI; upgrade the gateway so it returns structured error envelopes.","Verify the request path and payload match the current Caveman API schema.","If it is a proxy error page (502/503), fix the reverse proxy / upstream gateway availability."],"exampleFix":"// before\ntry { await agentMcpRequest(\"POST\", \"/v1/agent/run\", body); }\ncatch (e) { console.log(e.message); } // \"Caveman API request failed (502).\"\n// after\ntry { await agentMcpRequest(\"POST\", \"/v1/agent/run\", body); }\ncatch (e) { console.error(e.message, e.statusCode, await rawBody); } // inspect status + raw body","handlingStrategy":"try-catch","validationCode":"const res = await fetch(`${baseURL}${path}`);\nif (!res.ok) {\n  const text = await res.text();\n  console.error(`Caveman API ${res.status}:`, text.slice(0, 500)); // inspect real cause\n}","typeGuard":"function isAgentMcpHTTPError(e: unknown): e is Error & { statusCode?: number; code: string } {\n  return e instanceof Error && e.name === \"AgentMcpHTTPError\";\n}","tryCatchPattern":"try {\n  await agentMcpRequest(\"POST\", path, body);\n} catch (e) {\n  if (isAgentMcpHTTPError(e)) {\n    if (e.code === \"cave_request_failed\") {\n      console.error(`HTTP failure (${e.statusCode ?? \"?\"}): check gateway version and request schema`, e.message);\n    }\n  } else throw e;\n}","preventionTips":["Keep gateway and CLI versions in sync so error envelopes are structured","Validate request payloads against the current API schema","Log response.status plus raw body on any non-ok response","Check reverse-proxy error pages (502/503) before blaming the CLI"],"tags":["http","api","network"],"backgroundTag":"http-error-response","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"}