Troubleshooting Noctra

Use this runbook when Noctra behaves unexpectedly. Prefer noctra doctor, service logs, and per-ticket agent logs before changing code.

First Checks

1. Run noctra doctor from the same host and config context as the service.
2. Check the startup banner in service logs; it prints the resolved backend, trigger mode, states or label, repo routing, review gate, auto-iterate, and notifications.
3. Inspect the per-ticket transcript under the configured log directory:

make tail TICKET=ENG-42
# or
tail -f logs/ENG-42.log

Config defaults to ~/.noctra/ for .env and logs/, but a checkout containing .env, .env.example, or go.mod uses the current directory.

Tickets Are Not Picked Up

Check the trigger mode first:

TRIGGER_MODE=state
TRIGGER_STATE=Next
IN_REVIEW_STATE=In Review

or:

TRIGGER_MODE=label
TRIGGER_LABEL=noctra
IN_REVIEW_STATE=In Review

Then verify:

1. LINEAR_TEAM_KEY matches the ticket prefix, such as ENG for ENG-42.
2. State and label names match Linear exactly; names are case-sensitive.
3. The Linear API key has workspace access to read issues and write comments/state changes.
4. The ticket's Linear project has a Repo: directive in its description, or REPO_PATH is set as a fallback.

Query Linear states directly when names are unclear:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  --data '{"query":"{ team(key: \"ENG\") { states { nodes { name } } } }"}' \
  https://api.linear.app/graphql | jq '.data.team.states.nodes[].name'

Wrong Repo Or No Changes

Noctra routes each ticket to the repo named in its Linear project's Repo: directive. Confirm the project description (or content body) contains a line like:

Repo: your-org/web-app
Branch: main

owner/name expands to a GitHub HTTPS URL; full https:// / git@ URLs work verbatim. Branch: is optional (defaults to the repo's default branch). If the directive is missing, Noctra falls back to REPO_PATH when present. If neither exists, it skips the ticket with a Linear comment.

If the agent changed irrelevant files, improve the ticket with the writing-good-tickets skill and requeue it with specific files, errors, and acceptance criteria.

Agent Does Not Start

Check the selected backend:

grep '^AGENT_BACKEND=' .env

For Claude:

claude --version
claude

For Codex:

codex --version
codex login

A run that fails because the agent CLI isn't logged in doesn't use up a retry: Noctra comments 🔑, holds the ticket, and waits. Log in, then /requeue <ticket> (or Retry on the dashboard). Requeueing also resets a ticket's retry count, so a ticket that hit MAX_RETRIES can run again without restarting Noctra.

Noctra inherits CLI auth from the host unless API keys are supplied. In containers, use API-key auth instead of interactive login:

ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...

Agent Teams Is Not Active

Agent Teams is Claude-only. Verify:

AGENT_BACKEND=claude
USE_AGENT_TEAMS=true

The value must be true (or 1/yes, any case). Check the ticket log for the backend run header and use a recent claude CLI.

Gemini Review Fails Or Seems Wrong

If every review errors or fails before useful comments appear:

1. Confirm GEMINI_API_KEY is set only when the review gate is desired.
2. Validate the key with a direct API call.
3. Check Noctra's service log (noctra logs) for the gemini review lines; there is no separate Gemini log file.
4. If the diff is huge, split the ticket or reduce scope.

curl -s \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Say hello"}]}]}' | jq .

Gemini returning PASS on weak work usually means the review prompt or ticket acceptance criteria are too broad. Tighten the ticket and consider increasing MAX_REVIEW_RETRIES.

PR Creation Fails

Check GitHub auth and repo write access:

gh auth status
git ls-remote origin

For HTTPS remotes in containers, provide GH_TOKEN; the entrypoint wires it into gh and git.

Common fixes:

1. Log in as the GitHub account with repo write access.
2. Delete a stale remote branch if a prior run left one behind:

git push origin --delete noctra/eng-42

3. Check the ticket log for the exact gh pr create error.

Auto-Iterate Does Not React

Verify:

AUTO_ITERATE_PRS=true
MAX_PR_ITERATIONS=3
PR_POLL_INTERVAL=120
TRUSTED_REVIEWERS=

Noctra only watches PRs it authored, identified by the noctra/<id> branch prefix plus the Noctra marker in the PR body. It ignores bot feedback unless the bot login is in TRUSTED_REVIEWERS. CI failures are keyed by head commit SHA and are acted on once per failing commit.

The restart-safe cursor is stored in the SQLite DB at ~/.noctra/state.db unless STATE_DB overrides it. Deeper behaviour is in the auto-iterate skill.

A Repository Was Transferred Or Renamed

Symptom: a daily 🔑 Repositories alert, or github: skipping repo / lessons: failed to get PR details with not_installed, naming the old owner/name. Noctra cannot follow the move by itself, because the token service won't mint a token for the old name, and for a private repository GitHub only returns the redirect to a caller that already has access. With Noctra stopped (noctra stop):

1. Point the Linear project's Repo: line at the new name.
2. Delete the old clone (find it with noctra repos list). It holds nothing that isn't on GitHub, and Noctra re-clones from the directive when a ticket needs it.
3. Back up state.db, then rewrite the old URLs in pr_states.pr_url and the repo_lessons.repo slugs (<owner>-<name>, lower case). An open PR left under its old URL is never watched again. If the new URL already has a row, delete the old one instead of renaming it.

Then noctra start.

Cleanup After A Crash Or Bad Run

Prefer the built-in cleanup command:

./noctra cleanup
./noctra cleanup --force

Manual cleanup, when needed:

cd /path/to/repo
git worktree remove --force ~/.noctra-worktrees/ENG-42
git worktree prune
git branch -D noctra/eng-42 2>/dev/null || true
git push origin --delete noctra/eng-42

Move the Linear ticket back to the trigger state, or requeue it from Telegram:

/requeue ENG-42 More context for the next attempt.

Useful Logs

make logs                    # systemd service log
make watch                   # most recent agent transcript
make tail TICKET=ENG-42      # one ticket transcript
ls -lt logs/*.log | head     # recent local checkout logs

Noctra has no inbound server, webhook, ngrok tunnel, or port requirement. It polls Linear and GitHub over outbound HTTPS.