Skip to main content
Most problems with Gentic fall into one of three categories: the host 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 configured auth details, service state, backend, PID and uptime when available, boot state, and external tool checks. It does not currently test API connectivity or report the last poll.
The agent host polls the Gentic API every few seconds looking for issues in the todo pool. If an issue sits on todo indefinitely, the host is either not running or cannot reach the API.Step 1 — Check whether the host is running:
If the host is stopped, start it:
Step 2 — Verify credentials are configured:
You should see a host id, masked host credential, and valid API URL. If any registration value is missing, generate a host code in Gentic and reconnect:
If setup was interrupted after connecting, run gentic onboard to resume without another code.Step 3 — Restart the host:If the host shows as running but issues are still not being picked up, restart it to clear any stale state:
Then watch the issue — it should move to Queued and then In Progress within a few seconds if the host is healthy.
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 Agent activity. 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 — Retry the agent if it is genuinely stuck:If agent activity has been idle for more than 15 minutes and no error appears, use Retry with Claude Code or the adjacent agent dropdown. This clears the stored run state and conversation, then returns the issue to todo for a fresh session.
A run-failed status means the agent started but could not complete the task before opening a pull request. 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 Agent activity. 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:Step 3 — Retry the agent:After fixing the underlying issue, click Retry with Claude Code or choose another agent from its dropdown. The issue moves back to todo and the host attempts a fresh run on its next poll.
Automatic publishing starts only after a successful agent turn that changed the repository, while Create PR automatically is enabled and no pull request is attached.Step 1 — Check the issue preference and transcript:Open Edit issue and check Create PR automatically. Existing issues remain opted out, and the database and non-web API default is false. If a pull request is already attached, the preference is shown only as historical data.A valid automatic attempt appears as a visible Gentic-authored message in the same run. Gentic never hides commit, push, or pull-request instructions in the agent’s system prompt.Step 2 — Check how the run ended:Gentic skips automatic publishing for unchanged, failed, held, usage-limited, cancelled, and interrupted runs. It attempts publishing at most once per active run. Send a user follow-up after the run ends to start a later run that can try again.Step 3 — Publish idle work manually:If the issue is idle with unpublished changes and no pull request, click Create PR in the sidebar. The button is intentionally hidden while a run or automatic attempt is active and after any pull request is attached.Step 4 — Check a mixed-version deployment:Roll out this feature in this order: apply the database migration, deploy the web app and API, then update agent hosts. This order preserves compatibility because old issues and non-web callers default to automatic publishing disabled.
A held status means the agent hit a usage limit, session limit, rate limit, or quota during its last run. The host parses a reset time out of the error message and skips the issue until that time has passed.Step 1 — Check the parsed reset time:Open the issue detail page. The status badge shows when the host will retry (for example, “held until 15:00 UTC”). Until that timestamp, no host will claim the issue — even if you restart it.Step 2 — Wait, or reassign the run:In most cases, waiting is correct. The host automatically re-claims the issue on the first poll after the reset time and resumes the same agent session, so the transcript context is preserved.If you cannot wait, use the retry dropdown to start a fresh run with a different provider. Retrying clears the stored conversation and pull-request links for the issue.Step 3 — If the reset time looks wrong:The host recognises relative resets (try again in 2h), absolute timestamps, and HH:MM (UTC)-style formats emitted by Claude Code and Codex. If a reset time cannot be parsed out of the error, the run is marked run-failed instead so you can intervene manually.
Gentic clones repositories over SSH using the GIT_REMOTE_BASE setting (default: git@github.com:). If git fails to clone, the host’s SSH key is not trusted by GitHub.Step 1 — Test SSH connectivity from the host server:
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 host (if you do not already have one): ssh-keygen -t ed25519 -C "gentic-host"
  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:
With a project repo of acme/api, the cloned URL becomes git@github.com:acme/api.
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.
If gentic start appears to succeed but the host 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:
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 three values that cause an immediate exit if missing are:
Verify them with gentic auth status. If they are missing, generate a host code in Gentic and run gentic host connect <code> to save them.Step 3 — Check for port or network conflicts:The host does not bind to a port, but it does make outbound HTTPS requests to GENTIC_API_URL. Ensure the host can reach that URL from the command line:
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:
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.
Host management replaced the old shared GENTIC_API_KEY bearer token with a host-specific credential (GENTIC_HOST_CREDENTIAL) issued per machine. This is an intentional, alpha-stage breaking change — the API no longer accepts the old shared key at all, and there is no automatic migration of a previously running agent process into a host identity.If a host that used to work now fails every poll with 401:
  1. Upgrade the gentic CLI on that machine to a version that supports gentic host connect (see Installation).
  2. Remove GENTIC_API_KEY from its environment — it is no longer read.
  3. In Settings → Workspace → Hosts, click Connect host to generate a code, then run gentic host connect <code> on that machine.
  4. Run gentic onboard if setup didn’t finish automatically, then gentic start (or gentic restart).
This enrolls the machine as a new host — no live credentials are changed automatically, and no prior host identity is carried over. See Hosts → Re-enrolling an existing host for the full walkthrough.
If a completed, run-failed, or cancelled issue moves back to todo 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 by moving the status back to todo. 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 host from picking it up.