{"record":{"id":"49382e2ccb20cd43","repo":"JuliusBrussee/caveman","slug":"runtime-unavailable","errorCode":null,"errorMessage":"runtime_unavailable","messagePattern":"runtime_unavailable","errorType":"error_code","errorClass":"MiddlewareError","httpStatus":null,"severity":"error","filePath":"packages/sdk/typescript/src/middleware/runtime.ts","lineNumber":353,"sourceCode":"    const response = await untilAborted(pending,combined);\n    const reader = response.body?.getReader();\n    if (!reader) throw new MiddlewareError('invalid_plan');\n    let size = 0;\n    const chunks: Uint8Array[] = [];\n    try {\n      for (;;) {\n        const next = await untilAborted(reader.read(),combined);\n        if (next.done) break;\n        size += next.value.length;\n        if (size > 4 << 20) throw new MiddlewareError('payload_limit');\n        chunks.push(next.value);\n      }\n    } finally { void reader.cancel().catch(() => {}); reader.releaseLock(); }\n    const bytes = new Uint8Array(size);\n    let offset = 0;\n    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }\n    const data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) as { error?: { code?: unknown } };\n    if (!response.ok) throw new MiddlewareError(isToken(data.error?.code) ? data.error.code : 'runtime_unavailable');\n    return data;\n  }\n}\n\nexport function createMiddlewareRuntime(options: RuntimeOptions = {}): MiddlewareRuntime { return new MiddlewareRuntime(options); }\n","sourceCodeStart":335,"sourceCodeEnd":359,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/sdk/typescript/src/middleware/runtime.ts#L335-L359","documentation":"MiddlewareError('runtime_unavailable') is the fallback error thrown by exchange() when the runtime returns a non-OK HTTP status whose error body either lacks a code or has a code that fails the isToken check (/^[a-zA-Z0-9._:/-]{1,256}$/). It means the runtime could not serve the request but did not provide a recognized machine-readable error code.","triggerScenarios":"Any non-2xx response from the runtime — 500 crashes, 502/503 from a proxy, 401/403 from auth middleware — where data.error.code is missing, null, or contains characters outside the allowed token set (spaces, unicode, etc.).","commonSituations":"Runtime server not started or crashed; reverse proxy returning HTML error pages with no JSON error code; wrong endpoint port or path; token auth rejected upstream returning a nonstandard error body.","solutions":["Check that the runtime service at options.endpoint is running and reachable","Inspect the actual HTTP status/body from the endpoint with curl to find the real failure","Verify the endpoint URL, port, and any reverse-proxy routing","Check auth: if options.token is set, confirm it is accepted by the runtime"],"exampleFix":"// before\nconst runtime = createMiddlewareRuntime({ endpoint: 'http://127.0.0.1:8787' }); // runtime not started\n// after\n// start the runtime first, then verify:\n// curl http://127.0.0.1:8787/<PREFIX>capabilities\nconst runtime = createMiddlewareRuntime({ endpoint: 'http://127.0.0.1:8787' });\nawait runtime.ready();","handlingStrategy":"retry","validationCode":"const reachable = await fetch(endpoint + '/capabilities').then(r => r.ok).catch(() => false);\nif (!reachable) skipOptimization();","typeGuard":null,"tryCatchPattern":"try { return await runtime.optimize(req); } catch (e) { if (e instanceof MiddlewareError && e.code === 'runtime_unavailable') { backoff(); return sendUnoptimized(req); } throw e; }","preventionTips":["Health-check the runtime endpoint before first use (ready())","Monitor the runtime service and its proxies for 5xx/HTML error pages","Verify endpoint URL, port, and auth token configuration"],"tags":["network","http","availability"],"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"}