JuliusBrussee/caveman · error · MiddlewareError

code

Error message

code

What it means

bypass() is the internal escape hatch the runtime uses when it cannot optimize (circuit open, capacity, payload limits, deadline, etc.). Normally it returns a nonthrowing { status: 'bypassed', reason: code } result and emits an onDiagnostic callback; however, when options.strict is true it instead throws MiddlewareError(code), turning every bypass condition into a hard error with the bypass reason as the error code.

Solutions

1. Disable strict mode if bypasses should degrade gracefully (default behavior)
2. Catch MiddlewareError and inspect .code to handle specific bypass reasons
3. Fix the underlying bypass cause (e.g. raise limits, restore runtime availability) so the bypass stops occurring

Example fix

// before
const runtime = createMiddlewareRuntime({ strict: true }); // throws on any bypass
// after
const runtime = createMiddlewareRuntime({}); // bypasses return status:'bypassed' instead
try { await runtime.optimize(opts); } catch (e) { if (e instanceof MiddlewareError) console.warn(e.code); }

if (strictMode && !canTolerateHardFailures) throw new Error('strict mode will throw on any bypass');

try { await runtime.optimize(req); } catch (e) { if (e instanceof MiddlewareError) { switch (e.code) { case 'circuit_open': case 'capacity': case 'payload_limit': /* degrade gracefully */ } } else throw e; }

When it happens

Trigger: Any bypass path (circuit_open, capacity, payload_limit, deadline, invalid_scope, etc.) reached while the runtime was constructed with strict: true; the thrown message is 'Caveman middleware: <reason>'.

Common situations: Running with strict mode enabled in production to surface compression failures loudly, then hitting routine conditions like an open circuit after runtime failures; mixing a strict-configured runtime with a flaky runtime server.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• cave_mastra_max_steps_invalid
• caveman agent: context id is required
• caveman agent: memory recallBudget must be a non-negative…
• invalid_deadline
• maxLoadedTools must be a positive integer

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

Appendix: source

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

  }

  close(): void { this.lifetime.abort(new MiddlewareError('closed')); this.capsCache.value = null; }

  /** Native adapters use this when their installed framework is untested.
   * No content or network request is sent. Strict mode remains explicit. */
  decline(reason: 'unsupported_version'): Optimization {
    if (this.mode === 'off') return { status: 'off', reason: 'disabled', replacements: [], plan: null, request: null, cacheContinuity: 'off' };
    return this.bypass(reason);
  }

  /** Header controls are restricted to an explicitly configured, discovered runtime origin. */
  isRuntimeOrigin(url: string): boolean {
    try { return this.capsCache.value !== null && new URL(url).origin === this.endpoint; } catch { return false; }
  }

  private bypass(code: string, diagnostic = true): Optimization {
    if (diagnostic) { try { this.options.onDiagnostic?.({ code, cacheContinuity: 'unavailable' }); } catch { /* sink cannot break requests */ } }
    if (this.options.strict && diagnostic) throw new MiddlewareError(code);
    return { status: 'bypassed', reason: code, replacements: [], plan: null, request: null, cacheContinuity: 'unavailable' };
  }

  private async http(path: string, body: string | undefined, timeoutMs: number, signal?: AbortSignal): Promise<unknown> {
    const deadline = new AbortController();
    const timer = setTimeout(() => deadline.abort(new MiddlewareError('deadline')),Math.max(1,Math.ceil(timeoutMs)));
    try {
      return await this.exchange(path,body,AbortSignal.any([this.lifetime.signal,deadline.signal,...(signal ? [signal] : [])]));
    } finally { clearTimeout(timer); }
  }

  private async exchange(path: string, body: string | undefined, combined: AbortSignal): Promise<unknown> {
    combined.throwIfAborted();
    const headers: Record<string,string> = { 'Content-Type': 'application/json' };
    if (this.options.token) headers['Authorization'] = `Bearer ${this.options.token}`;
    const receipt = path === 'receipts';
    if (receipt ? this.receiptFetchesPending >= 1 : this.fetchesPending >= 16) throw new MiddlewareError('capacity');
    if (receipt) this.receiptFetchesPending++; else this.fetchesPending++;

View on GitHub (pinned to 3ee70a1026)