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:

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

Jobs stuck in Ready

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

Steps to try:

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

Agent not detected

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

Steps to try:

1. 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.
2. Click Rescan Capabilities & Tools in the runner settings to re-detect installed agents.
3. If you installed the agent after opening the runner, a rescan should pick it up.
4. 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.

GitHub push failures

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

Steps to try:

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

Agent execution errors

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

Steps to try:

1. 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.
2. Verify the agent has the necessary credentials configured (e.g., Anthropic API key for Claude Code).
3. If the issue is intermittent, the runner may have already retried automatically. Check if the job has recovered.
4. Try retrying the job manually — open the job in Coord and click Retry.

Runner using too many resources

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

Steps to try:

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

Tool approval timeout

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

Steps to try:

1. Check the runner's Status tab for any pending approval prompts.
2. Approve or deny the requested action. The agent cannot continue until you respond.
3. 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.

Blank white window on Linux

Symptoms: On Linux, the Coord Runner opens but shows only a blank white window — no content ever renders. If you launched it from a terminal, you may see an error mentioning EGL_BAD_PARAMETER or Could not create default EGL display.

This happens on some systems (most often those with recent graphics drivers) when graphics libraries bundled inside the AppImage conflict with the ones already installed on your machine.

Steps to try:

1. Update to the latest Coord Runner. Recent versions no longer bundle the conflicting graphics libraries, which resolves this on most systems. Update from within the app — click Check for Updates in the runner settings — or download a fresh .AppImage and replace your existing copy.
2. If you are on an older version or cannot update yet, launch the runner through a small wrapper script that forces it to use your system's own graphics libraries:

   #!/bin/sh
   export WEBKIT_DISABLE_COMPOSITING_MODE=1
   export WEBKIT_DISABLE_DMABUF_RENDERER=1
   export GDK_BACKEND=x11
   export LD_PRELOAD=/usr/lib/libwayland-client.so.0:/usr/lib/libwayland-egl.so.1:/usr/lib/libwayland-cursor.so.0:/usr/lib/libwayland-server.so.0
   exec ./Coord-Runner-linux.AppImage "$@"

   Save it next to the AppImage (for example as run-coord-runner.sh), make it executable with chmod +x run-coord-runner.sh, then run it instead of the AppImage directly.

Note: If your distribution keeps system libraries somewhere other than /usr/lib (for example /usr/lib64 or an architecture-specific path), adjust the paths in LD_PRELOAD to match.

Sign-in fails on Linux (keyring not set up)

Symptoms: On Linux, you complete sign-in in your browser and see it succeed there, but the Coord Runner still says sign-in failed. If you launched it from a terminal, you may see a message mentioning secure storage or no result found.

This happens on a fresh Linux install where your system keyring — the secure store your desktop uses for passwords and tokens — has never been set up. The runner can't save your sign-in until the keyring exists.

Steps to try:

1. Update to the latest Coord Runner and sign in again. Recent versions detect an unset keyring and prompt you to choose a keyring password during sign-in. Enter a password to create the keyring, and sign-in completes.
2. If you aren't prompted (for example on a server or shared machine with no desktop session), set the keyring up once yourself, then sign in again:
   • With a desktop app: open Passwords and Keys (Seahorse), create a new Login keyring, and set a password for it.
   • From a terminal: run secret-tool store --label='Coord' service coord key init, and set a password when asked. (Provided by the libsecret tools — install libsecret-tools or gnome-keyring if secret-tool is missing.)
3. Make sure a keyring service is installed and running. Most desktops include gnome-keyring or KWallet; install one if your system has neither.

Note: A keyring password protects your saved sign-in. You'll typically be asked to unlock the keyring once per login session.

Next steps

• Configuration — adjust runner settings
• Agent capabilities — agent-specific details
• Set up GitHub integration — verify GitHub is connected correctly