Troubleshooting

If you hit a problem, try the relevant section below before emailing support. The fixes here are derived from the actual codebase and known fork-specific gotchas; nothing on this page is hypothetical.

Windows SmartScreen blocks the installer

The current beta build is not yet code-signed, so Windows shows “Windows protected your PC” the first time you launch the installer.

1. Click More info at the top of the dialog.
2. Click Run anyway.
3. The installer takes about 30 seconds; launch Agentslan from the Start menu when it finishes.

This is expected; nothing is wrong with the file.

The local server takes a long time to start

On Windows installations sitting on NTFS, the bundled server can take 30–60 seconds to start the first time. Large dependency trees plus NTFS small-file overhead account for the wait. Don’t assume failure until you’ve waited a full minute on the first launch.

If startup is still failing after a minute:

1. Check the logs (see “Where logs live” below).

2. Confirm port 3100 is not already in use (netstat -ano | findstr :3100 on Windows). The local API and UI both listen on that port.

3. Quit any background Agentslan processes that might still be running. On Windows, open Task Manager and kill any leftover Agentslan or node processes. On macOS or Linux, use Activity Monitor or:

   pkill -f "Agentslan"
   pkill -f "tsx.*index.ts"

“Port 3100 is already in use”

The Agentslan dev/local server listens on port 3100. If something else is on that port, Agentslan won’t start.

# Windows
netstat -ano | findstr :3100

# macOS / Linux
lsof -i :3100

Either kill the offending process or change Agentslan’s port via the desktop app’s settings. If port 3100 is busy at app start, Agentslan auto-falls back to 3101 and upward.

Reset local data

Agentslan stores its database in a hidden local data directory under your home folder. To reset the local database and start fresh:

1. Quit the desktop app completely (check the system tray).

2. Delete the local data directory:

   # macOS / Linux
   rm -rf ~/.paperclip/instances/default/db
   
   # Windows PowerShell
   Remove-Item -Recurse -Force "$HOME\.paperclip\instances\default\db"

3. Restart Agentslan. It will recreate the database and run migrations from scratch.

This deletes every project, issue, agent, routine, and run history on the host. Custom adapter configurations and skills also live here. Make sure nothing is unsynced before you proceed.

An agent never starts

If you dispatch an issue but the agent stays in queued or running forever:

1. Confirm the underlying CLI is signed in. Run the CLI directly (claude, codex, gemini, agent, opencode, or pi) in a terminal on the host machine. If it works in the terminal, it’ll work from Agentslan.
2. Check the agent’s budget. Per-agent and per-company budgets are enforced as a hard 100% stop. If a budget is exhausted, the scheduler skips the invocation. Raise the budget or reset it from the company settings.
3. Verify nothing is paused. The scheduler skips agents whose status is paused or terminated, and skips invocations when a previous run is still active.
4. Check the run logs for the issue. Agentslan streams the underlying CLI’s stdout/stderr; the failure mode is usually visible there before anything else.

For OpenClaw specifically, the very first run on a fresh gateway can come back as pairing required. Approve the device in OpenClaw and retry; see the OpenClaw adapter page for the full pairing flow.

Where logs live

Agentslan writes server-side logs into the same local data directory as the database:

• The instance root holds server logs, instance state, and per-company managed runtimes.
• Per-company codex-home/ subdirectories hold Codex-specific managed state when you use the Codex adapter.
• An adapter-plugins.json file at the data-directory root lists any registered external adapter plugins.

When a specific run goes wrong, the per-run transcript is the most useful artefact — open the issue, click the run, and copy the transcript.

How to file a useful bug report

Email support@agentslan.com with:

1. Your OS and Agentslan version (visible in the desktop app’s About dialog).
2. Which adapter you were using and the model ID, if relevant.
3. Steps that reproduce the problem.
4. The run transcript (for agent failures) or the relevant log file (for app crashes).

Without those four, we usually can’t help; with them, we usually can.