> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gentic.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Gentic Worker, Auth, and Agent Run Issues

> Solutions for common problems with the Gentic agent worker, GitHub integration, and issue runs — including auth errors, stuck issues, and agent failures.

Most problems with Gentic fall into one of three categories: the worker is not running or not authenticated, the agent encountered an error during a run, or GitHub access is not set up correctly. Work through the relevant accordion below for step-by-step fixes.

<Note>
  Run `gentic status --json` for machine-readable diagnostics you can pipe into other tools or include in a support request. The JSON output includes worker state, API connectivity, last poll timestamp, and the active configuration (with the API key masked).
</Note>

<Accordion title="Issue stuck on 'queued' — agent never starts">
  The agent worker polls the Gentic API every few seconds looking for queued issues. If an issue sits on `queued` indefinitely, the worker is either not running or cannot reach the API.

  **Step 1 — Check whether the worker is running:**

  ```bash theme={null}
  gentic status
  ```

  If the worker is stopped, start it:

  ```bash theme={null}
  gentic start
  ```

  **Step 2 — Verify credentials are configured:**

  ```bash theme={null}
  gentic auth status
  ```

  You should see a masked API key and a valid API URL. If either is missing, re-authenticate:

  ```bash theme={null}
  gentic auth login
  ```

  Supply your `GENTIC_API_URL` (e.g. `https://gentic.chat/api/v1`) and your `GENTIC_API_KEY` when prompted.

  **Step 3 — Restart the worker:**

  If the worker shows as running but issues are still not being picked up, restart it to clear any stale state:

  ```bash theme={null}
  gentic restart
  ```

  Then watch the issue — it should move to `In Progress` within a few seconds if the worker is healthy.
</Accordion>

<Accordion title="Issue stuck on 'in-progress' — agent appears frozen">
  An issue that stays on `In Progress` for an unexpectedly long time may mean the agent is still working (some tasks take several minutes), is waiting for a slow external call, or has genuinely stalled.

  **Step 1 — Check the transcript:**

  Open the issue and scroll to the **Transcript** panel. If you see recent output, the agent is still active. Complex tasks can take 5–15 minutes — give it time before intervening.

  **Step 2 — Look for a "waiting for input" state:**

  If the issue status has moved to `Waiting for input`, the agent has paused and is expecting a message from you. Send a reply in the transcript to continue.

  **Step 3 — Reset the agent if it is genuinely stuck:**

  If the transcript has been idle for more than 15 minutes and no error appears, use **Reset Agent** on the issue detail page. This cancels the current run and re-queues the issue so the worker picks it up fresh on the next poll.
</Accordion>

<Accordion title="run_status shows 'failed'">
  A `failed` run means the agent started but could not complete the task. The most useful diagnostic is the transcript.

  **Step 1 — Read the transcript for an error message:**

  Open the issue and scroll to the bottom of the **Transcript** panel. The agent usually prints the error that caused it to stop — a git authentication failure, a missing dependency, or a tool error.

  **Step 2 — Fix the underlying cause:**

  Common failure causes and their fixes:

  | Cause                                              | Fix                                                                                                                          |
  | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
  | Git clone failed (`Permission denied (publickey)`) | Add an SSH deploy key or machine user key to the GitHub repository. See the [agent can't clone the repo](#) accordion below. |
  | Agent credentials invalid or expired               | Re-authenticate Claude Code or Codex on the worker machine.                                                                  |
  | Repository not found (404)                         | Confirm the project `owner/repo` in Settings is correct and the worker's SSH key has access.                                 |
  | Out of disk space                                  | Free up disk on the worker machine; the work directory defaults to `~/.local/share/gentic/workspaces`.                       |

  **Step 3 — Reset the agent to retry:**

  After fixing the underlying issue, click **Reset Agent** on the issue detail page. The issue moves back to `queued` and the worker attempts the run again.
</Accordion>

<Accordion title="Agent can't clone the repo (git error)">
  Gentic clones repositories over SSH using the `GIT_REMOTE_BASE` setting (default: `git@github.com:`). If git fails to clone, the worker's SSH key is not trusted by GitHub.

  **Step 1 — Test SSH connectivity from the worker server:**

  ```bash theme={null}
  ssh -T git@github.com
  ```

  A successful response looks like: `Hi username! You've successfully authenticated, but GitHub does not provide shell access.`

  If you see `Permission denied (publickey)`, the key is not authorised.

  **Step 2 — Add a deploy key to the GitHub repository:**

  1. Generate an SSH key pair on the worker machine (if you do not already have one): `ssh-keygen -t ed25519 -C "gentic-worker"`
  2. Copy the **public** key: `cat ~/.ssh/id_ed25519.pub`
  3. In GitHub, open the repository → **Settings → Deploy keys → Add deploy key**.
  4. Paste the public key, give it a descriptive title, and leave **Allow write access** enabled (the agent pushes branches).

  **Step 3 — Verify `GIT_REMOTE_BASE` is correct:**

  Check your `.env` or config file. The value must end with a colon for the `owner/repo` concatenation to produce a valid SSH URL:

  ```bash theme={null}
  GIT_REMOTE_BASE=git@github.com:
  ```

  With a project repo of `acme/api`, the cloned URL becomes `git@github.com:acme/api`.
</Accordion>

<Accordion title="GitHub integration shows 'Pending approval'">
  If your GitHub integration status shows **Pending approval**, the Gentic GitHub App has been installed but your GitHub organisation administrator has not yet approved it.

  Until an organisation admin approves the App installation, Gentic cannot read or write to repositories in that organisation.

  **What to do:**

  1. Ask your GitHub organisation admin to navigate to **GitHub → Organisation settings → GitHub Apps** (or the direct approval link sent by GitHub when the install request was created).
  2. The admin approves the Gentic App installation for the organisation.
  3. Return to Gentic Settings — the integration status should update to **Active** within a few seconds.

  If the approval link has expired, re-initiate the installation from Gentic Settings.
</Accordion>

<Accordion title="Worker starts but immediately stops">
  If `gentic start` appears to succeed but the worker is not running moments later (confirmed by `gentic status`), the process is exiting due to a startup error.

  **Step 1 — Run in the foreground to see error output directly:**

  ```bash theme={null}
  gentic run
  ```

  Unlike `gentic start`, `gentic run` keeps the process in the foreground and prints all output to your terminal. The error that is causing the crash will be visible immediately.

  **Step 2 — Check that required configuration is present:**

  The two values that cause an immediate exit if missing are:

  ```bash theme={null}
  GENTIC_API_KEY=<your-api-key>
  GENTIC_API_URL=https://gentic.chat/api/v1
  ```

  Verify them with `gentic auth status`. If they are missing, run `gentic auth login` to save them.

  **Step 3 — Check for port or network conflicts:**

  The worker does not bind to a port, but it does make outbound HTTPS requests to `GENTIC_API_URL`. Ensure the worker machine can reach that URL from the command line:

  ```bash theme={null}
  curl -I https://gentic.chat/api/v1
  ```
</Accordion>

<Accordion title="macOS: &#x22;gentic&#x22; cannot be opened because it is from an unidentified developer">
  The standalone `gentic` binary is compiled with Bun and is **not code-signed or notarized**. macOS Gatekeeper will block the first launch.

  **Option A — Right-click to open:**

  Right-click (or Control-click) the `gentic` binary in Finder and choose **Open**. macOS will prompt you to confirm; click **Open** again. Gatekeeper remembers this choice for subsequent launches.

  **Option B — Remove the quarantine attribute from the terminal:**

  ```bash theme={null}
  xattr -d com.apple.quarantine ./gentic
  ```

  After running this command, `./gentic` launches normally without a Gatekeeper prompt.

  <Warning>
    Only run binaries from sources you trust. Verify the SHA-256 checksum of the downloaded archive against the `checksums.txt` published with each GitHub Release before removing the quarantine attribute.
  </Warning>
</Accordion>

<Accordion title="Issue re-queues itself unexpectedly">
  If a completed, failed, or cancelled issue moves back to `queued` without you explicitly triggering it, a message was sent to the issue — either by you, a team member, or an automation.

  **This is expected behaviour.** Sending any message to an issue that has already finished its run automatically re-queues it. The agent resumes the same session (using the stored `session_id`) so the full prior conversation is available as context. This makes it easy to continue iterating: just send a follow-up message describing the next change.

  If you do not want the agent to run again, change the issue status to `Cancelled` after the re-queue occurs to stop the worker from picking it up.
</Accordion>