JuliusBrussee/caveman · error · MiddlewareError

runtime_unavailable

Error message

runtime_unavailable

What it means

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.

Solutions

1. Check that the runtime service at options.endpoint is running and reachable
2. Inspect the actual HTTP status/body from the endpoint with curl to find the real failure
3. Verify the endpoint URL, port, and any reverse-proxy routing
4. Check auth: if options.token is set, confirm it is accepted by the runtime

Example fix

// before
const runtime = createMiddlewareRuntime({ endpoint: 'http://127.0.0.1:8787' }); // runtime not started
// after
// start the runtime first, then verify:
// curl http://127.0.0.1:8787/<PREFIX>capabilities
const runtime = createMiddlewareRuntime({ endpoint: 'http://127.0.0.1:8787' });
await runtime.ready();

const reachable = await fetch(endpoint + '/capabilities').then(r => r.ok).catch(() => false);
if (!reachable) skipOptimization();

try { return await runtime.optimize(req); } catch (e) { if (e instanceof MiddlewareError && e.code === 'runtime_unavailable') { backoff(); return sendUnoptimized(req); } throw e; }

When it happens

Trigger: 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.).

Common situations: 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.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• runtime_unavailable
• awscreds: sts assume role with web identity failed
• binary download failed: HTTP
• cave_agent_tool_timeout | cave_network_error
• cave_request_failed

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

Appendix: source

Thrown at packages/sdk/typescript/src/middleware/runtime.ts:353

    const response = await untilAborted(pending,combined);
    const reader = response.body?.getReader();
    if (!reader) throw new MiddlewareError('invalid_plan');
    let size = 0;
    const chunks: Uint8Array[] = [];
    try {
      for (;;) {
        const next = await untilAborted(reader.read(),combined);
        if (next.done) break;
        size += next.value.length;
        if (size > 4 << 20) throw new MiddlewareError('payload_limit');
        chunks.push(next.value);
      }
    } finally { void reader.cancel().catch(() => {}); reader.releaseLock(); }
    const bytes = new Uint8Array(size);
    let offset = 0;
    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
    const data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) as { error?: { code?: unknown } };
    if (!response.ok) throw new MiddlewareError(isToken(data.error?.code) ? data.error.code : 'runtime_unavailable');
    return data;
  }
}

export function createMiddlewareRuntime(options: RuntimeOptions = {}): MiddlewareRuntime { return new MiddlewareRuntime(options); }

View on GitHub (pinned to 3ee70a1026)