# How to Debug Issues in DeepSeek-Reasonix: A Complete Troubleshooting Guide

> Debug DeepSeek-Reasonix AI agent issues effectively. Learn to enable verbose logging, inspect workspace leases, and analyze trajectory recordings for swift troubleshooting.

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

---

**Enable verbose logging with `LOG_LEVEL=debug`, inspect workspace leases in [`internal/workspacelease/lease.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/workspacelease/lease.go), and analyze trajectory recordings via [`internal/trajectory/recorder.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/trajectory/recorder.go) to isolate failures in the DeepSeek-Reasonix AI-agent framework.**

DeepSeek-Reasonix is a modular, cross-platform AI-agent framework built with Go and Wails. Its architecture splits functionality into distinct layers—including the core engine, workspace management, and trajectory systems—making it possible to debug issues in DeepSeek-Reasonix by isolating problems to specific subsystems.

## Understanding the Architecture Layers

DeepSeek-Reasonix organizes code into clear responsibility layers. Knowing which layer exhibits symptoms helps you navigate to the correct source files immediately.

| Layer | Purpose | Main Packages |
|-------|---------|---------------|
| **Core Engine** | Orchestrates agents, handles sessions, and enforces capability diagnostics | `desktop/`, `sdk/go/` |
| **Workspace Management** | Tracks file-system changes, provides leases for exclusive access, and maintains a worktree view | `internal/workspacelease/`, `internal/worktree/` |
| **Trajectory & Diagnostics** | Records reasoning steps and supplies diagnostics for debugging | `internal/trajectory/` |
| **Updater & Platform Integration** | Manages auto-updates, platform-specific UI, and WebView2 runtime | `desktop/updater*`, `desktop/webview2_*` |
| **CLI & Tools** | Provides command-line interface and auxiliary utilities | `cmd/`, `tools/` |

## Step-by-Step Debugging Workflow

When an issue surfaces, follow this systematic approach to pinpoint the root cause.

### Reproduce the Problem Locally

Start by running the binary or `go run ./cmd/...` with the exact inputs that triggered the failure. Consistent reproduction is the prerequisite for any diagnostic work.

### Enable Verbose Logging

The framework uses a custom logger implemented in [`desktop/wails_logger.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/wails_logger.go). Set the environment variable `LOG_LEVEL=debug` or pass `-loglevel debug` on the CLI to obtain detailed execution traces.

```bash
export LOG_LEVEL=debug
go run ./cmd/reasonix

```

With debug logging active, the application emits granular timing and state information that reveals where execution diverges from the expected path.

### Inspect Workspace State

File-system event detection happens in [`desktop/workspace_watch.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workspace_watch.go). Review logs from the workspace watcher to verify that the agent correctly detected changes in the target directory. Missing events here indicate permission issues or watcher exhaustion at the OS level.

### Verify Lease Acquisition

Race conditions often stem from the lease mechanism implemented in [`internal/workspacelease/lease.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/workspacelease/lease.go). Check logs for "cannot acquire lease" errors. Verify that `NewLease()` returned successfully and that `Release()` is called in a deferred manner.

```go
lease, err := workspacelease.NewLease("/path/to/workspace")
if err != nil {
    logger.Error("Failed to acquire lease", err)
    return
}
defer lease.Release()

```

### Analyze Trajectory Recordings

The recorder in [`internal/trajectory/recorder.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/trajectory/recorder.go) writes a JSON trail of reasoning steps. After execution, load the trajectory file in the Capability Diagnostics view to see exactly where the agent deviated.

```go
recorder := trajectory.NewRecorder()
agent.RunTask(ctx, recorder)
if err := recorder.Save("debug_trajectory.json"); err != nil {
    logger.Error("Unable to save trajectory", err)
}

```

### Leverage Wails Development Tools

When running the desktop UI in development mode with `wails dev`, Chrome DevTools become available. Inspect network requests, console errors, and UI state just as you would in a standard web application. This is invaluable for debugging frontend-agent communication issues.

### Run the Built-in Test Suite

The repository ships extensive unit and integration tests in `*_test.go` files throughout the codebase. Executing `go test ./...` quickly isolates regressions and confirms whether your environment satisfies all dependencies.

```bash
go test ./...

```

## Common Edge Cases and Platform-Specific Pitfalls

Certain failures are specific to operating system implementations or runtime dependencies.

### Platform-Specific UI Failures

Windows and macOS have distinct implementations for tray icons and updater logic in [`tray_supported_windows.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/tray_supported_windows.go) and [`updater_windows.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/updater_windows.go). Ensure the correct files are compiled for your target OS by checking build tags in the source.

### WebView2 Runtime Errors

On Windows, the WebView2 runtime must be installed. The startup code in [`desktop/webview2_startup.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/webview2_startup.go) logs a clear fatal error if the runtime cannot be located. Install the Evergreen Standalone Installer if you encounter initialization panics.

### Concurrent Workspace Modifications

If multiple processes modify the same workspace, lease contention causes "cannot acquire lease" errors. Use the lease API to serialize access as shown in [`internal/workspacelease/lease.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/workspacelease/lease.go), ensuring exclusive writes.

### Missing Configuration Files

The framework expects a TOML configuration file (see [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml)). Missing required keys produce panics with explicit file-line references pointing to [`docs/CONFIG_PATHS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CONFIG_PATHS.md) for resolution.

## Practical Code Examples for Debugging

Combine logging, lease verification, and trajectory capture in a single debugging harness:

```go
// Enable debug logging for the entire application
os.Setenv("LOG_LEVEL", "debug")
logger := wails.NewLogger()
logger.SetLevel(wails.LogLevelDebug)

// Acquire a lease for a workspace path
lease, err := workspacelease.NewLease("/path/to/workspace")
if err != nil {
    logger.Error("Failed to acquire lease", err)
    return
}
defer lease.Release()

// Run an agent task and capture its trajectory
recorder := trajectory.NewRecorder()
agent.RunTask(ctx, recorder)

// After execution, write the trajectory to a file for inspection
if err := recorder.Save("debug_trajectory.json"); err != nil {
    logger.Error("Unable to save trajectory", err)
}

```

This pattern ensures you capture exclusive access logs, detailed execution traces, and full reasoning trajectories in one run.

## Summary

- **Enable verbose logging** via `LOG_LEVEL=debug` and [`desktop/wails_logger.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/wails_logger.go) to expose internal state.
- **Verify workspace leases** in [`internal/workspacelease/lease.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/workspacelease/lease.go) to eliminate race conditions.
- **Capture trajectory recordings** using [`internal/trajectory/recorder.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/trajectory/recorder.go) to audit agent reasoning.
- **Use `wails dev`** for frontend debugging with Chrome DevTools.
- **Run `go test ./...`** to isolate environmental regressions.
- **Check platform-specific files** like [`desktop/webview2_startup.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/webview2_startup.go) for OS-dependent failures.

## Frequently Asked Questions

### How do I enable debug mode in DeepSeek-Reasonix?

Set the environment variable `LOG_LEVEL=debug` before starting the application, or pass `-loglevel debug` when invoking the CLI. This activates the custom logger in [`desktop/wails_logger.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/wails_logger.go) and outputs detailed traces to stderr.

### What should I do if the agent cannot acquire a workspace lease?

This indicates another process holds the lock. Check [`internal/workspacelease/lease.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/workspacelease/lease.go) to ensure your code calls `NewLease()` successfully and defers `Release()`. If the issue persists, verify no orphaned processes are holding leases using OS-specific file-lock inspection tools.

### Where are trajectory recordings stored and how do I read them?

The [`internal/trajectory/recorder.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/trajectory/recorder.go) package writes JSON files via the `Save()` method. You specify the path—commonly [`debug_trajectory.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/debug_trajectory.json)—and load this file into the Capability Diagnostics view in the UI or inspect it manually to see the step-by-step reasoning chain.

### Why does the desktop application fail to start on Windows with a WebView2 error?

The application requires the Microsoft Edge WebView2 runtime. If [`desktop/webview2_startup.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/webview2_startup.go) logs a missing runtime error, install the WebView2 Evergreen Standalone Installer from Microsoft's distribution site. The framework specifically checks for this dependency during initialization.