Troubleshooting

Troubleshooting

Start with the Settings tab (5): its Prerequisites section checks most of what can go wrong and says how to fix it. c runs the checks again after you fix something.

Fast Lane won't start

• "the GitHub CLI (gh) is required": install it from cli.github.com and run gh auth login.
• "gh auth: … (run gh auth login)": Fast Lane uses the GitHub CLI's login. Run gh auth login, then gh auth status to check.
• A config error naming a file and setting: the config has something Fast Lane can't use, such as a filter that doesn't apply to its kind (labels on an alert), an unknown action, an unknown effort, or a prompt that doesn't parse. Fix that entry, or move the file aside to start fresh.

A missing claude doesn't stop Fast Lane from starting: the Settings tab shows it, and you can set Claude path there.

Repos or items are missing

• Private or organization repos don't show up: the GitHub login needs the repo and read:org scopes. Run gh auth refresh -s repo,read:org.
• No Dependabot or code scanning alerts: the repo must have them enabled, and you need permission to see its security alerts. Repos where they aren't available are skipped quietly.
• A repo shows "failed to sync": the message says why. Network trouble clears up on the next poll; R retries now.

Nothing runs on its own

Work through these in order:

1. Is auto-run on? For repo triggers, the repo must show auto on the Repos tab. Inbox triggers follow the inbox setting on the Rules or Settings tab instead.
2. Was the item there before? Items that existed when you started watching never auto-run, and the first poll after you upgrade Fast Lane only records state. Start these by hand with enter.
3. Do the rules cover it? Once any rule exists, only the keys the rules list auto-run. A checks_failed change needs a pull_request:checks_failed rule. A repo with rules of its own ignores the global rules.
4. Does it pass the filters? authors means who opened the item, not who commented. The status line says how many new changes "didn't match auto rules".
5. Was it your own activity? Your pushes and comments, and bot comments, never trigger anything.
6. Has it hit the limit? The status line says when an item "reached max_auto_runs". Raise it on the Settings tab if you need to.

Sessions

• A session failed while preparing: the transcript shows the git error. A failed git fetch isn't fatal; a failed git worktree add or gh repo clone is. Check that the checkout or the workspace folder is writable and that git works there.
• "branch is already checked out at …": you have that branch checked out in your own checkout. Claude knows to check it out under another name and push to the original branch; if it gets stuck, reply telling it to do that.
• A session says "interrupted when Fast Lane exited": Fast Lane was quit mid-turn. Press enter on it and reply to continue.
• Claude keeps asking for permission for the same thing: answer a in the dialog to allow it for the rest of the session, add the action to the rule's allow list, or add the tool to Allowed tools on the Settings tab for every session.
• Something went wrong and you want the details: each session's raw log is in ~/.local/state/fast-lane/logs/session-<n>.jsonl.

The inbox

• Review requests or mentions don't show up: the Settings tab's Notifications check must pass; it needs the repo or notifications scope. The first read after you turn the inbox on only records the time, so only newer notifications appear.
• Too much from the inbox: set it to list only (i on the Rules tab), or add rules for pull_request:mentioned, issue:mentioned and the others with filters such as skip_labels.

Disk space

Worktrees share your checkouts' git objects, so they're small, but each one is a full copy of the files. Worktrees of sessions finished over a week ago are removed at startup; D on the Sessions tab removes one right away. Clones of repos without a local checkout stay in the workspace until you delete them.

Still stuck?

Open an issue with what you did, what you expected, and the version from fast-lane -version.