How to Troubleshoot Common Issues with DeepSeek-Reasonix

Most DeepSeek-Reasonix failures stem from configuration mismatches in reasonix.toml, permission rule conflicts, or sandbox path violations, all diagnosable via reasonix status, --debug logging, and the built-in session rewind utility.

DeepSeek-Reasonix is a Go-based AI coding agent that runs as a single static binary and orchestrates model reasoning through a plugin-driven workflow defined in reasonix.toml. This guide covers systematic troubleshooting workflows for the most common runtime failures, referencing specific source implementations like internal/tool/registry.go and internal/tool/builtin/writefile.go to help you diagnose and resolve issues quickly.

Understanding the DeepSeek-Reasonix Architecture

DeepSeek-Reasonix operates through four distinct layers that determine where failures typically originate:

1. Core Engine – The reasonix binary parses reasonix.toml, loads providers, and drives the model-tool loop.
2. Tool System – Each tool implements Execute/Preview interfaces; built-ins like write_file enforce sandbox constraints.
3. Permissions & Sandbox – A policy engine evaluates allow, ask, and deny rules before side-effecting actions, with denied rules taking precedence.
4. Bot Integration – Desktop clients expose Reasonix to Feishu, Lark, or WeChat via [[bot.connections]] configuration.

Bot Connection and Approval Failures

Bot Does Not Receive Messages

If your Feishu, Lark, or WeChat bot stops responding, the connection is likely unregistered or the QR code session has expired.

1. Open Settings → Bots in the desktop application.
2. Verify the connection status displays a green badge.
3. Re-scan the QR code to re-establish the session.

Reference the bot configuration schema in docs/BOT_GUIDE.md for connection string validation.

Approval Cards Never Appear

When tool approvals hang indefinitely, check for explicit deny rules in your permission policy.

Run reasonix config view or open reasonix.toml and inspect the [permissions] section. Remove or modify rules like Bash(rm -rf*) that explicitly deny the requested operation. Reload the session to apply changes.

Configuration and Permission Errors

Permission Denied Errors

The permission engine in internal/tool/registry.go evaluates rules before any tool execution. Denied rules take precedence over allow or ask settings.

To fix permission blocks:

• Change deny to ask for interactive approval.
• Remove overly broad wildcards that match legitimate tool calls.
• Verify the tool name matches the rule pattern exactly (case-sensitive).

Missing Configuration After Upgrade

Version upgrades from v0.x may leave conflicting files in ~/.reasonix that break the new TOML layout.

Run the migration command:

reasonix migrate

Or manually port critical fields from the old configuration to the new reasonix.toml structure as described in docs/MIGRATING.md.

Sandbox and File System Violations

"Outside Sandbox" Write Errors

The sandbox implementation in internal/tool/builtin/writefile.go rejects any file mutation outside the configured [sandbox] workspace_root.

Ensure your target path is inside the workspace directory, or explicitly add the directory to [sandbox] allow_write] in reasonix.toml:

[sandbox]
workspace_root = "/home/user/projects"
allow_write = ["/home/user/projects", "/tmp/buildArtifacts"]

Unexpected Tool Errors (e.g., "Mkdir error")

When tools return OS-level failures, the error usually originates from underlying system permissions or disk space constraints.

Inspect the CLI output and manually reproduce the operation:

mkdir -p /path/to/target

If the manual command fails, resolve the OS-level permission issue before retrying the agent operation.

API and Rate Limiting Issues

Rate Limit or Invalid API Key Errors

Provider credential issues surface when api_key_env points to an unset or expired variable.

1. Verify the environment variable exists:

   echo $DEEPSEEK_API_KEY

2. Confirm reasonix.toml references the correct variable name:

   [provider.deepseek]
   api_key_env = "DEEPSEEK_API_KEY"

3. Regenerate the key on the DeepSeek portal if authentication continues to fail.

Network Requests Blocked by SSRF Guard

The web_fetch tool in internal/tool/builtin/webfetch.go implements an SSRF guard that blocks internal network addresses by default.

For internal services, configure a trusted proxy:

[tool.web_fetch]
proxy = "http://corporate-proxy:8080"

Public endpoints should use HTTPS to avoid SSRF rejection.

Session Hangs and Performance Issues

Infinite Loops or Stalled Sessions

When the planner or executor exceeds step limits, the session appears to hang indefinitely.

Adjust the step limits in reasonix.toml (set to 0 for unlimited):

[agent]
max_steps = 50
planner_max_steps = 25

Configuration details are documented in docs/GUIDE.md.

General Debugging Workflow

When issues persist, follow this systematic diagnostic process:

1. Verify configuration integrity:

   cat reasonix.toml
   reasonix config view

2. Validate environment variables:

   env | grep -i key

3. Check system status:

   reasonix status

   This displays active sessions, tool-approval mode, and sandbox roots.

4. Enable verbose logging:

   reasonix serve --debug
   reasonix run "refactor this function" --debug

   Debug mode streams raw model requests and tool responses, exposing malformed JSON or missing arguments.

5. Rewind to a clean state: Use /rewind or double-press Esc in the UI to open the checkpoint picker and select the last known-good turn.

6. Approve pending operations via CLI: If the bot UI is unavailable:

   reasonix approve 3

Summary

• Configuration validation is the first step: use reasonix config view and verify reasonix.toml syntax after upgrades.
• Permission rules follow precedence: deny overrides allow; check internal/tool/registry.go logic if approvals behave unexpectedly.
• Sandbox violations require paths to be within workspace_root or explicitly listed in allow_write.
• Bot issues typically resolve by re-scanning QR codes in Settings → Bots.
• API failures require validating api_key_env variables and regenerating expired keys.
• Debug tools like reasonix status, --debug flags, and /rewind provide rapid visibility into runtime state.

Frequently Asked Questions

Why does DeepSeek-Reasonix reject file writes even when I have permissions configured?

The sandbox system in internal/tool/builtin/writefile.go evaluates paths before the permission engine processes rules. If the target path is outside [sandbox] workspace_root, the write is rejected regardless of permission settings. Add the specific directory to allow_write or move your project files into the workspace root.

How do I recover from a stuck approval loop when using Feishu or Lark bots?

Stuck approvals usually indicate a deny rule in reasonix.toml that matches the requested tool pattern. Run reasonix config view to identify blocking rules under [permissions], change deny to ask for interactive approval, and reload the session. If the bot UI is unresponsive, use reasonix approve <id> from the CLI to approve pending operations manually.

What causes "rate-limit" errors even with a valid DeepSeek API key?

Rate-limit errors occur when the provider throttles requests or when the API key has exceeded its quota. Verify your DEEPSEEK_API_KEY environment variable is exported in the shell running Reasonix (echo $DEEPSEEK_API_KEY). If the key is valid but limits persist, check the DeepSeek dashboard for usage quotas or implement retry logic by adjusting [agent] max_steps to reduce rapid-fire API calls.

How do I debug why a specific tool is not appearing in the approval queue?

Missing tools often result from registry failures or configuration reload issues. Run reasonix status to confirm the active toolset and session state. Enable verbose mode with reasonix serve --debug to inspect the raw model output and tool registration logs in reasonix.log, located in the Reasonix home directory. Check internal/tool/registry.go for the registration logic if custom tools fail to load.

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