# How to Report a Bug in DeepSeek-Reasonix: The Complete 2024 Guide

> Report bugs in DeepSeek-Reasonix effectively using GitHub issues. Follow our 2024 guide for clear titles, steps, and labels to ensure quick resolution.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Report bugs in DeepSeek-Reasonix by opening a GitHub issue with a clear title, reproducibility steps, expected vs. actual behavior, environment details, and the correct `v1` or `v2` label.**

DeepSeek-Reasonix is an open-source AI coding assistant with a multi-subsystem Go architecture. When you encounter a defect, following the project's established bug reporting protocol—defined in [`CONTRIBUTING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/CONTRIBUTING.md) and [`MIGRATING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MIGRATING.md)—ensures maintainers can reproduce and fix issues efficiently.

## Where to Submit Bug Reports

All bug reports for DeepSeek-Reasonix flow through GitHub Issues. The repository uses a structured template system to standardize incoming reports.

According to the source code in [`CONTRIBUTING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/CONTRIBUTING.md), you must:

1. Navigate to the project's GitHub Issues page
2. Click "New issue"
3. Select the bug report template

The template enforces specific sections that maintainers rely on for triage.

## Required Information for Every Bug Report

A complete DeepSeek-Reasonix bug report contains six essential components. Missing any of these typically results in a request for more information, delaying resolution.

### Steps to Reproduce

Provide a numbered list that any maintainer can execute. Include exact commands, configuration files, and input prompts.

```bash

# Example: CLI reproduction script for a file-encoding bug

cat > bug-repro.sh <<'EOF'
#!/usr/bin/env sh
reasonix run "write a file that contains a non-UTF-8 character"
EOF
chmod +x bug-repro.sh

```

Attach this script directly to your GitHub issue.

### Expected vs. Actual Behavior

State clearly what should happen versus what actually occurs. For crashes, include the full stack trace.

### Environment Details

Include:
- **Go version** (`go version`)
- **Operating system** and architecture
- **Reasonix version** (`reasonix version`)
- **Relevant configuration** from [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml)

```toml

# Example: Minimal config that triggers a provider bug

[providers.myprovider]
kind = "openai"
model = "deepseek-chat"
api_key = "REDACTED"

```

### Relevant Logs

Capture output from:
- CLI/TUI sessions
- Desktop application logs
- Provider API responses (with sensitive data redacted)

## Critical: Label Your Issue Correctly (`v1` vs `v2`)

DeepSeek-Reasonix maintains two distinct code lines. Accurate labeling determines which codebase receives the fix.

| Label | Codebase | Status | Use When |
|-------|----------|--------|----------|
| **`v2`** | Go implementation | Active development | Reporting bugs in current CLI, desktop app, or providers |
| **`v1`** | Legacy TypeScript | Maintenance mode only | Bugs in deprecated code, per [`docs/MIGRATING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/MIGRATING.md) |

As documented in [`MIGRATING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MIGRATING.md), the `v2` label applies to nearly all contemporary bug reports. Use `v1` only when specifically working with legacy TypeScript components.

## Subsystem-Specific Bug Reporting Tips

Understanding where bugs originate helps you provide targeted reproduction steps. The repository structure in `main-v2` organizes functionality into distinct packages:

### CLI Bugs (`internal/cli/`)

Most user-facing issues surface in the command-line interface. The entry point at `cmd/reasonix` handles argument parsing, configuration loading, and session initialization.

When reporting CLI bugs:
- Include the exact command with all flags
- Specify whether running in TUI mode (`-tui`) or headless
- Attach `~/.config/reasonix/history.json` if relevant

### Desktop Application Bugs (`desktop/`)

The Wails-based desktop application uses WebView2 on Windows and native web runtimes elsewhere. Report rendering issues, window management problems, or IPC failures here.

Include:
- WebView2 runtime version (Windows)
- Screenshots or screen recordings for UI glitches
- Browser console logs from the DevTools

### Provider Bugs (`internal/provider/`)

API-level issues with OpenAI-compatible or DeepSeek-specific backends belong here. Issues include authentication failures, rate limiting, malformed responses, or streaming interruptions.

Provide:
- Provider configuration (with `api_key` redacted)
- HTTP response traces (with `REASONIX_DEBUG=1` if available)
- Timestamp of failed request for server-side correlation

### Built-in Tool Bugs (`internal/tool/builtin/`)

File operations, process spawning, and sandboxing issues trace to this package. Common problems include:
- Permission errors in `write_file` or `read_file`
- Encoding mishandling in `str_replace`
- Sandbox escape attempts

## Optional: Attach a Minimal Reproducible Example

While not strictly required, a minimal reproducible example accelerates triage significantly. The best examples:
- Contain fewer than 20 lines of code or configuration
- Fail deterministically across clean environments
- Isolate the bug from project-specific context

## What Happens After You Submit

Maintainers follow a structured response workflow:

1. **Triage** (24-48 hours): Issue labeled and routed to appropriate subsystem maintainer
2. **Reproduction**: Maintainer attempts to reproduce using your steps
3. **Investigation**: Root cause analysis with potential workaround provided
4. **Fix PR**: Change proposed, linked to your issue
5. **Regression test**: CI pipeline adds automated test targeting the failure
6. **Closure**: Issue closed when fix merges to `main-v2`

Continue responding to clarification requests promptly. The `internal/cli/` test suite and subsystem-specific CI gates rely on accurate reproduction steps to generate regression tests.

## Summary

- Submit all DeepSeek-Reasonix bugs through GitHub Issues using the provided template
- Include steps to reproduce, expected/actual behavior, environment details, and logs
- **Label correctly**: `v2` for current Go code, `v1` only for legacy TypeScript
- Reference the appropriate subsystem: `internal/cli/`, `desktop/`, `internal/provider/`, or `internal/tool/builtin/`
- Attach minimal reproduction scripts when possible to speed up CI integration

## Frequently Asked Questions

### Do I need to know Go to report a bug in DeepSeek-Reasonix?

No. While understanding the repository structure helps position your report, you only need to describe the problem clearly and provide reproduction steps. Maintainers handle the implementation details in `internal/` packages. Focus on what you observed and how to trigger it.

### What if I'm not sure whether a bug is in `v1` or `v2`?

Default to `v2`. As documented in [`MIGRATING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MIGRATING.md), the `v2` codebase (current Go implementation) is the active development line. Only apply `v1` if you are explicitly running legacy TypeScript code from the pre-Go era. When in doubt, mention your installation method and version output from `reasonix version`.

### How quickly do maintainers respond to bug reports?

Typical initial triage occurs within 24-48 hours for well-structured reports. Issues missing environment details or reproduction steps may sit longer pending clarification. Critical security bugs or data-loss scenarios receive priority handling regardless of report completeness.

### Can I suggest a fix alongside my bug report?

Yes. The project welcomes pull requests that include both bug description and fix. Follow the format in [`CONTRIBUTING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/CONTRIBUTING.md), reference the issue number, and ensure your change includes a regression test in the relevant subsystem's test package (e.g., [`internal/provider/provider_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider_test.go)).