How to Report Bugs in OmniRoute: A Complete Guide for Contributors

Report bugs in OmniRoute by opening a GitHub issue using the Bug Report template, enabling Debug Mode to capture detailed traces from src/sse/handlers/chat.ts, and running npm run system-info to generate a complete environment snapshot.

OmniRoute is a highly modular LLM routing platform where failures can surface across multiple architectural layers. When you report bugs in OmniRoute, providing reproducible steps, environment details, and relevant log excerpts allows the core team to pinpoint failures in the routing pipeline. The repository provides a structured issue template, an automated system-information helper, and a debug-mode toggle to surface the exact internal state at the point of failure.

Enable Debug Mode and Capture System Information

Before submitting a report, configure your environment to expose diagnostic data that traces execution through the handler and executor layers.

Toggle Debug Mode in the Dashboard

Navigate to UI → Settings → Advanced → Debug Mode to activate detailed logging. When enabled, this setting persists via src/lib/db/settings.ts and injects log.debug calls into the SSE stream. Specifically, src/sse/handlers/chat.ts at line 425 writes detailed request/response traces that are filtered out in production but essential for debugging.

// src/app/dashboard/settings/AdvancedSettings.tsx (simplified)
import { useSettings } from '@/hooks/useSettings';

export function AdvancedSettings() {
  const { settings, updateSettings } = useSettings();

  return (
    <label className="flex items-center gap-2">
      <input
        type="checkbox"
        checked={settings.debugMode}
        onChange={e => updateSettings({ debugMode: e.target.checked })}
        className="toggle"
      />
      Debug Mode
    </label>
  );
}

Generate Environment Snapshots with the System-Info Script

Run npm run system-info from the repository root to execute the helper at scripts/dev/system-info.mjs. This generates a system-info.txt file containing your Node version, OmniRoute version (e.g., v3.8.50), OS details, installed providers, active configuration from open-sse/config/providerRegistry.ts, and the SQLite database path from src/lib/db/core.ts.

# From the repository root

npm run system-info   # defined in package.json scripts

# Generates ./system-info.txt

Step-by-Step Workflow to Report Bugs in OmniRoute

Follow this structured process to ensure maintainers can reproduce the issue across the API route, combo router, and executor layers.

1. Open a GitHub Issue using the Bug Report template at .github/ISSUE_TEMPLATE/bug_report.yml. This template forces structured input including severity, reproducible steps, and environment details, feeding directly into the CI triage pipeline.

2. Enable Debug Mode before reproducing the bug. This captures detailed traces in ~/.omniroute/logs/*.log that reveal which handler, executor, or translator misbehaved.

3. Run the system-info script (npm run system-info) and attach the generated system-info.txt. This provides the exact runtime environment including database schema versions from src/lib/db/core.ts.

4. Capture the failing request including the full JSON payload, headers (especially auth headers), and server response. OmniRoute validates input via Zod in src/app/api/v1/chat/completions/route.ts before passing it to the combo router at open-sse/services/combo.ts.

5. Attach relevant log excerpts showing DEBUG entries from the handler output. These logs show the exact transformer that generated the response, any retry/back-off logic, and the final error handling path.

6. Include a minimal reproducible script using the CLI wrapper at src/bin/omniroute.ts or a Node script using the OmniRoute client to demonstrate the bug end-to-end.

import { OmniRouteClient } from '@omniroute/client';

// Instantiate client pointing at local dev server
const client = new OmniRouteClient({ baseUrl: 'http://localhost:3000' });

async function reproduce() {
  const resp = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello world' }],
    stream: true,
  });

  for await (const chunk of resp) {
    console.log(chunk);
  }
}

reproduce().catch(console.error);

Run this script with DEBUG=omniroute:* npm start to capture full internal traces through the routing layers.

Key Architectural Components to Reference

When describing the bug, cite these specific source files to help maintainers locate the defect in the layered architecture:

• .github/ISSUE_TEMPLATE/bug_report.yml: The structured template that enforces consistent reporting standards.
• src/sse/handlers/chat.ts: Core chat handler emitting debug logs at line 425 when Debug Mode is active.
• src/app/api/v1/chat/completions/route.ts: Entry point for the Chat Completions API; validates input before dispatching to the combo router.
• open-sse/services/combo.ts: Implements the auto-combo routing strategy and provider fallback logic.
• open-sse/executors/default.ts: Default executor used for OpenAI-compatible providers.
• open-sse/translator/index.ts: Handles protocol translation between OpenAI, Anthropic, and Gemini formats—a common source of formatting bugs.
• src/bin/omniroute.ts: CLI entry point for command-line reproductions.
• src/lib/db/core.ts: SQLite instance and schema versioning; crucial for database migration-related bugs.

Understanding the Request Flow for Accurate Bug Reports

OmniRoute processes requests through a specific layered pipeline. Identifying where in this chain the failure occurs helps you collect the right logs and cite the correct source files:

API Route (Next.js) → Auth/Zod validation → Combo Router (open-sse/services/combo.ts)
      ↓
Resolved Target → Executor (open-sse/executors/*.ts)
      ↓
Request Translator (open-sse/translator/) → Upstream Provider
      ↓
Response Translator → SSE/JSON to client

When you report bugs in OmniRoute, specify whether the failure occurs during input validation (API route), routing selection (combo router), upstream execution (executor), or protocol translation (translator). This precision eliminates guesswork and accelerates the fix.

Summary

• Use the Bug Report template at .github/ISSUE_TEMPLATE/bug_report.yml to structure your submission with required environment details.
• Enable Debug Mode before reproduction to capture detailed traces from src/sse/handlers/chat.ts at line 425.
• Run npm run system-info to generate a complete environment snapshot via scripts/dev/system-info.mjs.
• Attach full request payloads, response codes, and log excerpts from ~/.omniroute/logs/*.log.
• Reference specific architectural layers—combo router (open-sse/services/combo.ts), executor (open-sse/executors/default.ts), or translator (open-sse/translator/index.ts)—when describing the failure location.

Frequently Asked Questions

Where do I find the Debug Mode toggle in OmniRoute?

Navigate to the dashboard UI at Settings → Advanced → Debug Mode. This updates the configuration via src/lib/db/settings.ts and activates debug logging in src/sse/handlers/chat.ts, writing detailed request/response traces to your local log directory at ~/.omniroute/logs/*.log.

What information does the system-info script collect?

The script at scripts/dev/system-info.mjs collects your Node.js version, OmniRoute version (e.g., v3.8.50), operating system, installed LLM providers from open-sse/config/providerRegistry.ts, active environment configuration, and the SQLite database path from src/lib/db/core.ts, outputting everything to a system-info.txt file.

How do I capture a minimal reproducible example for the CLI?

Use the CLI wrapper at src/bin/omniroute.ts to reproduce the bug from the command line, or provide a Node script using the OmniRoute client. Include the exact command with all flags, or the complete script that demonstrates the failure against a local instance running on localhost:3000.

Why should I reference specific source files in my bug report?

Citing files like open-sse/services/combo.ts (routing logic), open-sse/executors/default.ts (provider execution), or open-sse/translator/index.ts (protocol translation) immediately signals to maintainers which layer of the pipeline contains the defect. This specificity reduces triage time and helps the team verify the bug against the correct subsystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}