Troubleshooting

First work out which layer the problem lives in: the Kolleague service, the daemon, the runtime, or the AI coding tool. These commands are usually enough to surface the first meaningful error:

kolleague version
kolleague auth status
kolleague daemon status --output json
kolleague daemon logs --lines 100

Remove tokens, email addresses, and other sensitive details before sharing logs with support.

Daemon fails to connect

Run these first:

kolleague auth status
kolleague daemon status --output json
kolleague daemon logs --lines 100

Common causes include:

• The CLI has not signed in, or the token stored on this machine has expired.
• The executing computer cannot reach Kolleague because DNS, TLS, or a firewall blocks the connection.
• The current account is no longer a member of the target workspace.
• No supported AI coding tool is installed on this machine, so the daemon cannot start.

Sign in again and restart the daemon:

kolleague login
kolleague daemon restart

Issue does not start executing

Open the issue's execution log and check the task's current status and what it is waiting for.

queued status

queued means the task is still waiting for a runtime to claim it. Check in order:

1. Is the runtime the agent is bound to online?
2. Did the runtime detect the AI coding tool the agent is configured with?
3. Does the agent still have concurrency headroom?
4. Does the daemon still have global execution capacity?

An agent runs at most 6 tasks concurrently by default; a single daemon runs at most 20. At the limit, new tasks stay in the queue until a running one finishes. Tasks also keep queueing while the runtime is offline; they only fail after going unclaimed for more than 2 hours.

kolleague daemon status --output json
kolleague agent get <agent-id>
kolleague issue runs <issue-id>

If the runtime list is missing an expected tool, first confirm the tool runs and is signed in under the same system account and PATH, then run kolleague daemon restart.

waiting_local_directory status

This means another in-flight task is using the same local directory. Kolleague waits for the directory lock to be released so two agents never modify the same files at once.

Usually you just wait for the earlier task to finish. If it is stuck, stop it from its execution log, or pick a different local directory for the current agent. This directory mutex lives in the daemon's memory — no lock file is written to disk. If you suspect stale lock state, kolleague daemon restart releases it; there is nothing to delete manually.

AI coding tool fails to start

An online daemon does not mean the tool itself works. Open the run's detailed record and focus on:

• Whether the tool has completed sign-in.
• Whether the API key, quota, or model permissions are available.
• Whether the model and thinking level the agent selected are supported by the tool.
• Whether the local working directory exists and is writable.
• Whether the agent's custom arguments or environment variables are valid.

Run the same tool directly in a terminal on the executing computer first. If the tool cannot start on its own, fix its sign-in or configuration, then retry the task from the execution log.

Realtime updates stop working

If tasks still execute but comments and status changes no longer appear live, refresh the page and sign in again. Then restart the daemon and confirm its status:

kolleague daemon restart
kolleague daemon status --output json

If the problem continues, check the /ws request under Network → WS in the browser's developer tools and share the failed request status with support.

Log locations

To observe the daemon's startup directly, run it in the foreground instead:

kolleague daemon stop
kolleague daemon start --foreground

Next steps

• Daemon and runtimes — how runtimes register and report online status.
• Tasks — status, timeout, and failure reference.