Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

14.0 KB
Raw Blame

title: "Error Message Sanitization" version: 3.8.51 lastUpdated: 2026-09-02

Error Message Sanitization

Source of truth: open-sse/utils/errorSanitization.ts, open-sse/utils/errorPathRedaction.ts, and the public builders in open-sse/utils/error.ts Tests: tests/unit/error-message-sanitization.test.ts, tests/unit/error-public-boundaries-hardening.test.ts Last updated: 2026-09-02 — v3.8.51 Audience: Any engineer touching error responses (HTTP routes, SSE streams, executors, MCP handlers). Status: MANDATORY for every code path that returns an error message to a client.

Why this exists

CodeQL rule js/stack-trace-exposure (CWE-209) flags any code path where an error message originating from a runtime exception reaches an HTTP / SSE response without being sanitized. Stack traces and absolute file paths in production responses give attackers:

  • Internal directory layout (/srv/app/src/lib/...) → reconnaissance for further attacks.
  • Library / framework versions inferred from stack frames → targeted exploit selection.
  • Sensitive runtime values that may be string-interpolated into errors (DB queries, config values).

The sanitizeErrorMessage helper exported by open-sse/utils/error.ts strips these classes of leakage:

  1. Physical, serialized, and unambiguously inline JavaScript stack-frame tails.
  2. Absolute POSIX, Windows, UNC, and file:// filesystem paths, while preserving safe HTTPS URLs and explicitly marked API routes.
  3. Credential assignments, common provider token formats, private-key PEM blocks, and base64 data URLs.

The sanitizer caps input length and fails closed when a thrown value rejects string coercion. Recursive upstream JSON sanitization also drops unsafe credential/path keys, session aliases, and prototype-control keys before a response is serialized.

The mandatory pattern

1. Building an error response (HTTP / API routes)

Use buildErrorBody() — sanitization is built-in:

import { buildErrorBody } from "@omniroute/open-sse/utils/error.ts";

export async function POST(req: Request) {
  try {
    // ... handler logic ...
  } catch (err) {
    return new Response(JSON.stringify(buildErrorBody(500, String(err))), {
      status: 500,
      headers: { "Content-Type": "application/json" },
    });
  }
}

Or, for the convenience wrappers in the same module:

import {
  errorResponse, // one-shot Response object
  writeStreamError, // SSE writer
  createErrorResult, // { success: false, status, response, ... } shape
  unavailableResponse, // adds Retry-After
  providerCircuitOpenResponse,
  modelCooldownResponse,
} from "@omniroute/open-sse/utils/error.ts";

All of these apply the canonical public-error boundary. errorResponse, writeStreamError, and createErrorResult route through buildErrorBody; the three specialized retry/circuit helpers project and sanitize their public context directly. You never need to call sanitizeErrorMessage manually when using these helpers.

2. Custom error envelopes (rare)

When you can't use the helpers above (e.g. the response shape is dictated by an upstream protocol like Connect-RPC), import sanitizeErrorMessage directly:

import { sanitizeErrorMessage } from "@omniroute/open-sse/utils/error.ts";

const body = JSON.stringify({
  error: {
    message: sanitizeErrorMessage(rawMessage),
    type: "invalid_request_error",
    code: "",
  },
});

This is the only sanctioned way to assemble a custom error body. See open-sse/executors/cursor.ts::buildErrorResponse for the reference implementation.

3. Logging vs. responding

Trusted internal exceptions may keep their full message and stack so operators can debug. Values originating at provider, validation, browser-session, or credential-adjacent boundaries must be sanitized before they enter console output, audit metadata, or persistent call logs. Pattern:

try {
  // ...
} catch (err) {
  log.error({ err }, "handler failed"); // trusted internal exception only
  return errorResponse(500, getErrorMessage(err)); // sanitized — sent to client
}

For provider-controlled failures, project the logged value too:

log.error({ message: sanitizeErrorMessage(err) || "Provider request failed" });

4. Forbidden patterns

❌ Never put raw exception output in a Response body:

// BAD: stack trace + file paths reach the client
return new Response(JSON.stringify({ error: { message: err.stack || err.message } }), {
  status: 500,
});

❌ Never roll your own first-line splitter:

// BAD: forgets to strip absolute paths, may drift from the canonical helper
const safe = String(err).split("\n")[0];

❌ Never sanitize in the route and forget the SSE path. Anything that writes to a stream goes through writeStreamError (or its underlying buildErrorBody).

❌ Never intentionally include process.cwd(), __filename, __dirname, or env-derived paths in error messages. The sanitizer covers absolute paths as defense in depth, but callers must not construct topology-bearing messages in the first place.

Coverage in CI

tests/unit/error-message-sanitization.test.ts enforces:

  • Every route under /api/model-combo-mappings/* returns sanitized bodies on 4xx/5xx.
  • sanitizeErrorMessage strips multi-line stack traces.
  • sanitizeErrorMessage replaces POSIX and Windows absolute paths with <path>.
  • sanitizeErrorMessage handles null/undefined/Error instance inputs safely.
  • buildErrorBody never exposes stack traces in its message field.

When adding a new route or executor, copy the assertion pattern from this file. The coverage gate (npm run test:coverage) enforces ≥60% statements/lines/functions/branches — error paths must be covered.

The static gate: npm run check:error-helper

scripts/check/check-error-helper.mjs scans open-sse/executors/, open-sse/handlers/, open-sse/mcp-server/ and every src/app/api/**/route.ts for a raw caught error (err.message / err.stack) or a raw upstream body.error.message reaching a client-facing body.

Trust is call-scoped, never file-scoped (G-03, #15159). The gate used to skip an entire file the moment it saw any import from a utils/error path — a file-scoped exemption applied to a call-scoped hazard. One correct import { sanitizeErrorMessage } permanently excused every other sink in the file, which is how a live leak shipped green. Now a line is trusted only when it actually routes through a sanctioned builder or sanitizer:

Line shape Trusted?
calls sanitizeErrorMessage / buildErrorBody / createErrorResult / toSafeMcpErrorMessage / … yes
calls a canonical builder that this file imports from open-sse/utils/error or src/lib/api/errorResponse yes
a sanctioned builder is called multi-line, so the message: field sits on a later line yes
calls a file-local function errorResponse(...) whose own body sanitizes yes
forwards err.message / err.stack anywhere else no — violation

Two consequences worth knowing:

  • Importing errorResponse is not blanket trust. A file that defines its own errorResponse still gets flagged at the call site, because the gate resolves trust per symbol, not per file. The same holds for createErrorResponse.
  • const body = buildErrorBody(status, sanitizeErrorMessage(msg)) followed by error: body.error.message is the sanitized idiom used across the *-fetch.ts executors and is not flagged.

Both sanctioned builder modules count: open-sse/utils/error.ts and src/lib/api/errorResponse.ts. The second is what the ~54 route handlers outside open-sse use, and it sanitizes both of its exports.

Two shapes that are not violations, both of which the gate once reported as leaks:

  • a raw error inside an audit row — saveCallLog({ error: err.message }), logToolCall(...), or a logger that takes a message first (log.error("BATCHES", "sweep failed", { error: err.message })). The client-facing response on the next lines may well be a static buildErrorBody.
  • a multi-line sanctioned builder call, where the message: field names no builder at all:
    return createErrorResponse({
      status: 400,
      message: error.message,
    });
    

KNOWN_MISSING_ERROR_HELPER freezes pre-existing violations so the gate blocks only new ones. assertNoStale drops an entry automatically once its violation is fixed, so the freeze cannot ossify. Regression guards: tests/unit/check-error-helper.test.ts and tests/unit/check-error-helper-call-scope.test.ts.

Related controls

  • js/stack-trace-exposure CodeQL alerts in .github/security should always be either fixed via these helpers or dismissed with a comment citing this doc.
  • The pino redaction config (src/shared/utils/logRedaction.ts) handles trusted structured logs separately. This document covers public response messages and provider-controlled values that cross persistent call/proxy-log boundaries.
  • Upstream-header denylist (src/shared/constants/upstreamHeaders.ts) covers header leakage — keep both files aligned when adding a new exfiltration concern.

Upstream details passthrough

buildErrorBody accepts an optional third argument upstreamDetails (raw parsed body from the upstream provider). When provided, it is sanitized by sanitizeUpstreamDetails before inclusion in the response as upstream_details.

An optional fourth argument classification ({ type?: string; code?: string; reason?: string }) accepts an explicit public classification. Every field is projected onto the bounded public-identifier vocabulary. Unsafe, credential-shaped, control-character, or overlong values fall back to the status-derived type/code; an unsafe optional reason is omitted. Three-digit HTTP status identifiers (100 through 599) remain valid for provider contracts that expose the numeric upstream status as a machine-readable code. The same bounded range is accepted in the locally generated HTTP-status placeholder form; arbitrary provider numbers and names remain outside the vocabulary.

Pass every explicit classification in that fourth argument. Never overwrite body.error.code, body.error.type, or body.error.reason after buildErrorBody() returns; post-builder mutation bypasses the public projection.

Sanitization rules applied to upstreamDetails:

  1. String leaves: run through sanitizeErrorMessage (strips stacks + absolute paths).
  2. Unsafe path, credential, session-alias, and prototype-control keys are removed.
  3. Depth cap: nesting beyond 4 levels is replaced with the string "[truncated]".
  4. Arrays are capped at 32 elements.

Only call sites with a parsed provider error body should pass upstreamDetails. Internal OmniRoute errors (SSE parse failures, empty content, guardrail blocks) must not include it.

Do NOT pass raw err.stack, err.message, or any string from a runtime exception to upstreamDetails. Those must still go through errorResponse / buildErrorBody(code, msg) without an upstream body.

Selective upstream 4xx passthrough preserves the provider's safe JSON shape and wording required by client auto-recovery, but it is not byte-for-byte passthrough: the recursive sanitizer always runs before serialization. Cyclic, BigInt-bearing, or hostile toJSON() bodies fail closed and are not eligible for passthrough. OCR and moderation apply the same rule; non-JSON, blank, or mislabeled upstream bodies are converted to the canonical OmniRoute JSON error envelope.

Known CodeQL limitation: custom sanitizers not recognized

The CodeQL query js/stack-trace-exposure uses a fixed allowlist of sanitizer patterns (e.g. inline .split("\n")[0], String#replace with specific regex shapes, access to .message on Error). It does not recognize indirection through a custom helper like our sanitizeErrorMessage().

This means callsites that demonstrably sanitize via this module — for example open-sse/utils/error.ts::errorResponse and open-sse/executors/cursor.ts::buildErrorResponse — may continue to raise the alert even though the code is functionally safe. Precedent dismissals: #224, #231 (May 2026), both marked false positive with technical justification.

How to handle a new occurrence:

  1. Confirm the callsite actually routes the message through sanitizeErrorMessage / buildErrorBody / one of the wrappers documented above (read the call chain end-to-end — don't trust a comment).
  2. Confirm tests/unit/error-message-sanitization.test.ts exercises the path (or add coverage).
  3. Dismiss the alert via gh api ... -X PATCH state=dismissed -f 'dismissed_reason=false positive' referencing this doc.
  4. Do not "fix" by inlining .split("\n")[0] everywhere — the helper is the single source of truth; duplicating the pattern weakens the sanitizer (loses path scrubbing, length cap, type coercion) for the appearance of placating the scanner.

Adopting opt-in features like CodeQL's @codeql/javascript-models custom sanitizer config is the long-term fix; it lives outside this doc.

References