Diagnostics and Troubleshooting

Use this guide to diagnose and fix common operational issues in Zenborg.

---

1. Port Conflicts and Stale Server Locks

Symptoms

• Zenborg fails to start with an error stating the server is already running or port 3001 is in use.
• The interface does not load in your browser or electron window.

Cause

If Zenborg or your computer shut down unexpectedly, an orphaned background process may still hold port 3001, or a lock file was left behind on disk.

Solution

1. Check for Running Processes:
   • On macOS:

     lsof -i :3001

   • On Windows:

     netstat -ano | findstr :3001

2. Terminate the stale process if found (kill -9 <PID> on macOS or taskkill /F /PID <PID> on Windows).
3. Remove Stale Lock File: If no process is using port 3001, remove the stale lock file manually:

   rm data/server.lock

4. Restart Zenborg.

---

2. Provider 400, 429, and Overloaded Errors

Symptoms

• A stage fails with HTTP 400 Bad Request, HTTP 429 Too Many Requests, or 503 Overloaded.
• A stage stops with an error mentioning "Bad Request" or "overloaded".

Cause

• 400 Bad Request: Typically occurs when an agent prompt exceeds the model’s context window limit or contains invalid tool formatting.
• 429 / Overloaded: The upstream provider (Anthropic, OpenAI, or Google) has temporarily throttled your account or is experiencing high traffic.

Solution

1. Automatic Smart Worker Fallback: Zenborg automatically switches to the Smart Worker after two consecutive provider failures.
2. Resume Loop: Once rate limits expire, click the "Resume Loop" button in the loop detail panel. Zenborg picks up from the failed stage without restarting completed work.
3. Reduce Context Size: Ensure large build directories (node_modules/, dist/, .git/) are not being included in the prompt.

---

3. Empty Output and Stalled Stages

Symptoms

• An agent stage is marked failed with code STAGE_INACTIVE.
• The UI status turns amber and indicates "quiet · last activity ... ago".

Cause

• Stage Quiet Warning: After 5 minutes without log activity, Zenborg flags the stage as quiet.
• Inactivity Watchdog: If an agent produces zero output for 25 minutes (MAIOX_STAGE_INACTIVITY_MS), Zenborg marks the stage as stalled (STAGE_INACTIVE) to prevent hung tasks.

Solution

• Check your terminal or background processes. Some test suites or build commands run silently without outputting progress. Configure tests with verbose flags (--verbose) so Zenborg receives continuous heartbeat output.

---

4. Memory Safeguards and Out-of-Memory (OOM)

Symptoms

• A stage terminates with an error: "...stopped: its processes used ... MB, above the 6144 MB loop memory limit (MAIOX_LOOP_MAX_RSS_MB)"
• Or: "...stopped: system memory free fell to ...% (below 8%, MAIOX_LOOP_MIN_FREE_PERCENT)"

Cause

Autonomous workers running tests, compilers, or dev servers can consume excessive RAM. Zenborg terminates stages that exceed safety boundaries:

• Max Stage Resident Memory: 6,144 MB (6 GB).
• Node Heap Cap: 3,072 MB (3 GB).
• System Free Memory: Must remain above 8%.

Solution

1. Close memory-intensive applications (such as heavy Docker containers, unused IDEs, or games).

2. Check your project tests for memory leaks or runaway background servers.

3. Lower Agent Power to Low in the Agent Power settings to restrict loop concurrency.

4. Click "Resume Loop" to retry the stage.

---

5. CAPTCHA and Browser Login Issues

Symptoms

• A banner displays: "<Provider> needs you to log in".
• A banner states: "<Provider> hit a CAPTCHA; the loop continued on another agent."

Cause

The web provider requires human verification or session refresh in the dedicated browser profile.

Solution

1. Click the button labeled "Open browser to log in".
2. Solve the CAPTCHA puzzle or log in to your account.
3. Click "Resume loop" to continue the run.

---

6. License Issues and Key Reset

Symptoms

• The license section displays "Invalid key" or falls back to the Free plan.

Viewing Version and Build Details

To verify your current installation build:

1. Open the Settings dialog (#settingsDialog).
2. Scroll to the About section at the bottom.
3. Inspect #aboutVersionText to view your installed Zenborg version, packaging status, and build timestamp.

Resetting or Removing a Corrupt License Key

If you need to replace or delete an existing license key:

1. Open Settings (#settingsDialog).
2. Locate the button labeled "Remove key" (#settingsLicenceRemoveBtn).
3. Hold-to-Delete: To prevent accidental deletion, press and hold "Remove key" for 1.2 seconds (data-micro-hold="1200").
4. Paste your new key in #settingsLicenceKeyInput and click "Enter licence key".

---

Next Steps

• Review license tiers in Plans and Pricing.
• Find quick answers in the FAQ.