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

> Report bugs in OmniRoute effectively by opening a GitHub issue, enabling debug mode for detailed traces, and running npm run system-info for a complete environment snapshot.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts) and injects `log.debug` calls into the SSE stream. Specifically, [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) at line 425 writes detailed request/response traces that are filtered out in production but essential for debugging.

```tsx
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts), and the SQLite database path from [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts).

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/.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`](https://github.com/diegosouzapw/OmniRoute/blob/main/system-info.txt). This provides the exact runtime environment including database schema versions from [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) before passing it to the combo router at [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/bin/omniroute.ts) or a Node script using the OmniRoute client to demonstrate the bug end-to-end.

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml)**: The structured template that enforces consistent reporting standards.
- **[`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)**: Implements the **auto-combo** routing strategy and provider fallback logic.
- **[`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts)**: Default executor used for OpenAI-compatible providers.
- **[`open-sse/translator/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/index.ts)**: Handles protocol translation between OpenAI, Anthropic, and Gemini formats—a common source of formatting bugs.
- **[`src/bin/omniroute.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/bin/omniroute.ts)**: CLI entry point for command-line reproductions.
- **[`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/.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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)), executor ([`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts)), or translator ([`open-sse/translator/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts) and activates debug logging in [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts), active environment configuration, and the SQLite database path from [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts), outputting everything to a [`system-info.txt`](https://github.com/diegosouzapw/OmniRoute/blob/main/system-info.txt) file.

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

Use the CLI wrapper at [`src/bin/omniroute.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) (routing logic), [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) (provider execution), or [`open-sse/translator/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.