Troubleshoot Gentic Worker, Auth, and Agent Run Issues

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.

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).

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:

gentic status

If the worker is stopped, start it:

gentic start

Step 2 — Verify credentials are configured:

gentic auth status

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

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:

gentic restart

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

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.

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.

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:

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:

Generate an SSH key pair on the worker machine (if you do not already have one): ssh-keygen -t ed25519 -C "gentic-worker"
Copy the public key: cat ~/.ssh/id_ed25519.pub
In GitHub, open the repository → Settings → Deploy keys → Add deploy key.
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:

GIT_REMOTE_BASE=git@github.com:

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

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:

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).
The admin approves the Gentic App installation for the organisation.
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.

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:

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:

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:

curl -I https://gentic.chat/api/v1

macOS: "gentic" 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:

xattr -d com.apple.quarantine ./gentic

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

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.

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.