Troubleshooting

Solutions for common issues with the Coord Runner.

Runner not appearing online

Symptoms: The runner shows as offline on the Runners page, or jobs stay in Ready without being picked up.

Steps to try:

Check that the runner app is open and signed in.
Verify you are connected to the correct workspace.
Check your internet connection — the runner needs a stable connection to communicate with Coord.
Restart the runner app.
If the issue persists, sign out and sign back in.

Symptoms: Jobs stay in Ready and are not picked up by any runner.

Steps to try:

Confirm at least one runner is online in your workspace. Check the Runners page in the Coord web app.
Check that the runner has at least one agent enabled that matches the job requirements.
Verify your plan's concurrency limit has not been reached — if all available slots are in use, new jobs wait until a slot opens.
For repository jobs, confirm the repository is linked to your workspace via the GitHub integration.

Symptoms: The runner shows an agent as "Not found" even though you installed it.

Steps to try:

Verify the agent is installed and accessible from your terminal. Try running the agent's command in a terminal window: claude for Claude Code, codex for Codex, or gemini for Gemini CLI.
Click Rescan Capabilities & Tools in the runner settings to re-detect installed agents.
If you installed the agent after opening the runner, a rescan should pick it up.
On macOS, apps launched from the Dock may have a limited system PATH. If the agent works in Terminal but not in the runner, check that the agent's install location is in a standard path.

Symptoms: Agentic jobs fail when trying to push changes or create a pull request.

Steps to try:

Verify the GitHub integration is connected in your workspace settings.
Check that Coord Bot has access to the target repository. Go to your GitHub organization settings to verify.
Ensure the repository is not archived or read-only.
If branch protection rules are preventing the push, check your repository's branch protection settings on GitHub.

Symptoms: The agent starts but produces errors or fails to complete.

Steps to try:

Check the Logs tab in the runner for error messages. You can also check the job detail panel in the Coord web app for recorded output.
Verify the agent has the necessary credentials configured (e.g., Anthropic API key for Claude Code).
If the issue is intermittent, the runner may have already retried automatically. Check if the job has recovered.
Try retrying the job manually — open the job in Coord and click Retry.

Symptoms: Your machine slows down while the runner is executing jobs.

Steps to try:

Reduce the Max concurrent jobs setting in the runner. Running fewer jobs in parallel uses less CPU and memory.
Close other resource-intensive applications while the runner is active.
Consider moving some execution to a shared machine with more resources. See Team runners for details.

Symptoms: A job seems stuck, and the runner is showing a tool approval prompt you may have missed.

Steps to try:

Check the runner's Status tab for any pending approval prompts.
Approve or deny the requested action. The agent cannot continue until you respond.
Note that the one-hour execution timeout pauses while the agent is waiting for your input, so the job is not at risk of timing out while you decide.