# How to Troubleshoot Common Issues with DeepSeek-Reasonix

> Troubleshoot DeepSeek-Reasonix issues by diagnosing configuration mismatches, permission conflicts, and sandbox violations using status checks, debug logging, and session rewind.

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

---

**Most DeepSeek-Reasonix failures stem from configuration mismatches in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml). This guide covers systematic troubleshooting workflows for the most common runtime failures, referencing specific source implementations like [`internal/tool/registry.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/registry.go) and [`internal/tool/builtin/writefile.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```bash
reasonix migrate

```

Or manually port critical fields from the old configuration to the new [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) structure as described in [`docs/MIGRATING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/MIGRATING.md).

## Sandbox and File System Violations

### "Outside Sandbox" Write Errors

The sandbox implementation in [`internal/tool/builtin/writefile.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml):

```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:

```bash
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:
   ```bash
   echo $DEEPSEEK_API_KEY
   ```

2. Confirm [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) references the correct variable name:
   ```toml
   [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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/builtin/webfetch.go) implements an SSRF guard that blocks internal network addresses by default.

For internal services, configure a trusted proxy:

```toml
[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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) (set to `0` for unlimited):

```toml
[agent]
max_steps = 50
planner_max_steps = 25

```

Configuration details are documented in [`docs/GUIDE.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/GUIDE.md).

## General Debugging Workflow

When issues persist, follow this systematic diagnostic process:

1. **Verify configuration integrity**:
   ```bash
   cat reasonix.toml
   reasonix config view
   ```

2. **Validate environment variables**:
   ```bash
   env | grep -i key
   ```

3. **Check system status**:
   ```bash
   reasonix status
   ```

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

4. **Enable verbose logging**:
   ```bash
   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:
   ```bash
   reasonix approve 3
   ```

## Summary

- **Configuration validation** is the first step: use `reasonix config view` and verify [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) syntax after upgrades.
- **Permission rules** follow precedence: `deny` overrides `allow`; check [`internal/tool/registry.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/registry.go) for the registration logic if custom tools fail to load.