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

Enable verbose logging with LOG_LEVEL=debug, inspect workspace leases in internal/workspacelease/lease.go, and analyze trajectory recordings via 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. Set the environment variable LOG_LEVEL=debug or pass -loglevel debug on the CLI to obtain detailed execution traces.

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. 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. Check logs for "cannot acquire lease" errors. Verify that NewLease() returned successfully and that Release() is called in a deferred manner.

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 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.

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.

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 and 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 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, ensuring exclusive writes.

Missing Configuration Files

The framework expects a TOML configuration file (see reasonix.example.toml). Missing required keys produce panics with explicit file-line references pointing to docs/CONFIG_PATHS.md for resolution.

Practical Code Examples for Debugging

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

// 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 to expose internal state.
• Verify workspace leases in internal/workspacelease/lease.go to eliminate race conditions.
• Capture trajectory recordings using 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 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 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 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 package writes JSON files via the Save() method. You specify the path—commonly 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 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.

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