Troubleshooting

#No Eligible Issues

Symptoms:

• roark auto --dry-run prints no selected issues.
• Scheduled autorun exits without claiming work.

Check:

gh issue view 123 --repo owner/repo --json labels,state,assignees

Common causes:

• issue is closed
• missing ready label, default afk
• issue has a skip label
• custom --label, --skip-label, or --skip-labels does not match the repository label policy

Read Label semantics.

#Missing Required Labels

Symptoms:

• dry run reports missing labels
• autorun stops before claiming work

Normal autorun can create required lifecycle labels. Dry run reports missing labels without creating them.

Use a non-dry autorun when you are ready for Roark to create missing required labels, or create labels manually with gh label create.

#GitHub Authentication Fails

Symptoms:

• gh auth status fails
• scheduled jobs work manually but fail under cron or launchd
• GitHub API calls return permission errors

Check as the same user that runs Roark:

gh auth status
gh repo view owner/repo

For launchd, run under the user's login session so keychain credentials are available. For GitHub Actions, set GH_TOKEN and repository permissions.

#Verification Command Missing

Symptoms:

• auto or continue refuses to publish because no verification command is configured

Fix:

{
  "verify": "bun run check"
}

Or pass:

roark auto --repo owner/repo --verify "bun run check"

See Verification.

#Verification Fails Because Ignored Files Are Missing

Symptoms:

• verification.md shows missing .env, .secrets, credentials, generated config, or other ignored files

Fix by copying path names, not secret values:

{
  "workspace": {
    "copyToWorktree": [".secrets/env"]
  }
}

The destination must be ignored by Git. See Managed workspaces and Security and secrets.

#Dirty Managed Workspace

Symptoms:

• a fresh auto run refuses an existing issue workspace
• command output says to use continue or clean/remove the workspace

Use:

roark continue 123 --repo owner/repo

If the work is no longer needed:

roark workspace remove --issue 123 --force

Do not remove a workspace if it may contain recoverable uncommitted work.

#Branch Already Exists

Symptoms:

• branch creation or checkout fails
• issue branch already exists locally or remotely

Roark issue branches use:

roark/issue-<number>

Inspect:

git branch --list 'roark/issue-*'
git ls-remote --heads origin 'roark/issue-*'

If the branch belongs to a previous attempt, prefer roark continue. If it is unrelated, rename or remove it deliberately.

#Readiness Fails

Symptoms:

• readiness.md does not contain ready-for-pr
• no PR is opened

Open:

.roark/runs/issue/<n>/attempts/<k>/readiness.md

Then inspect the latest review and fix logs. Use continue after addressing local setup issues.

#PR Not Opened

Common causes:

• readiness failed
• verification failed
• push failed
• GitHub token lacks contents:write or pull request permissions
• branch head is not publishable

Inspect summary.json, verification.md, command output, and GitHub auth state.

#PR Revision Makes No Commit

revise-pr does not commit when:

• all feedback is already addressed
• all actionable feedback is classified needs-human, non-blocking, or invalid/stale
• verification fails
• the working tree is dirty and preflight refuses to continue

See PR revisions.

#Scheduler Runs Overlap

Symptoms:

• issue claiming races
• dirty workspace surprises

Use scheduler-level serialization:

• flock for cron
• concurrency for GitHub Actions
• one launchd job per control checkout

See Scheduling and Operations runbook.

#Useful First Files

For issue attempts:

.roark/runs/issue/<n>/attempts/<k>/summary.json
.roark/runs/issue/<n>/attempts/<k>/verification.md
.roark/runs/issue/<n>/attempts/<k>/readiness.md
.roark/runs/issue/<n>/attempts/<k>/events.jsonl

For PR revisions:

.roark/runs/pr/<pr-number>/revision-<n>/

See Artifacts.