Troubleshooting

Solutions for common issues and debugging steps for Autopilot CLI.

If you run into issues with Autopilot CLI, this guide will help you diagnose and fix them.

First Steps: The Doctor

Before diving into specific issues, run the built-in diagnostic tool. It checks your environment, git configuration, and permissions.

autopilot doctor

If autopilot doctor reports all green checks but you still have issues, check the specific scenarios below.

Common Issues

Autopilot detects changes but never commits

Symptoms: You see "Change detected" logs repeatedly, but no commit is ever created.

Cause:

1. Debounce Reset: "Noisy" files changing constantly (e.g., every second) keep resetting the debounce timer.
2. Ignored Files: You are editing files that are ignored by .gitignore or .autopilotignore.
3. Blocked Branch: You are on a protected branch (e.g., main, master, production) where auto-commits are disabled by default.

Fixes:

1. Check Blocked Branches: Check your .autopilotrc.json. By default, main and master are blocked to prevent accidental pushes to production.

"blockedBranches": ["main", "master", "production"]

2. Check Ignored Files: Autopilot respects .gitignore and has internal hardcoded ignores for:

• .git/
• node_modules/
• .vscode/ (and other IDE folders)
• autopilot.log & .autopilot.pid

If you are editing a file inside .vscode or node_modules, Autopilot will intentionally ignore it to prevent noise.

3. Debounce Issues: If a file changes every second, Autopilot keeps waiting for it to "settle".

• Identify the noisy file (check autopilot.log).
• Add it to .autopilotignore.
• Note: Autopilot now has a "Max Wait" fallback (default 60s) which forces a commit even if changes are still happening, preventing total starvation.

Push fails or "Authentication failed"

Symptoms: Autopilot commits locally but fails to push to the remote.

Cause: Autopilot uses your system's git credentials. If you haven't set up an SSH key or a credential helper (like git-credential-manager), background pushes might fail because they can't prompt for a password.

Fix: Ensure you can run git push manually in your terminal without being asked for a password.

• SSH: Set up an SSH key and add it to GitHub/GitLab.
• HTTPS: Use a credential helper to cache your token.

Autopilot start crashes immediately

Symptoms: You run autopilot start and it exits with an error.

Cause:

1. Node Version: Autopilot requires Node.js v18+.
2. Corrupted Install: Sometimes global packages get into a bad state.

Fix: Check your node version:

node -v
# Should be v18.0.0 or higher

Reinstall the package:

npm uninstall -g autopilot-cli
npm install -g autopilot-cli

Stop or Status commands aren't working

Symptoms: autopilot status says "Running" but it isn't, or autopilot stop says "No process found".

Cause: The .autopilot.pid file (which stores the process ID) might be stale. This happens if the computer crashed or the process was killed forcefully (e.g., via Task Manager) without cleaning up.

Fix: Manually delete the PID file to reset the state.

rm .autopilot.pid

AI commit generation fails with a model error

Symptoms: You see an OpenRouter error like:

This model is unavailable for free

Cause: The configured model slug is no longer part of the free tier or was pinned manually.

Fix:

• Set "model": "default" in .autopilotrc.json.
• Optionally set AUTOPILOT_OPENROUTER_MODELS to a comma-separated list of free model slugs.
• Make sure OPENROUTER_API_KEY is set in your environment.

Leaderboard sync returns a 500 error

Symptoms: Failed to sync leaderboard: Server responded with 500.

Cause: The docs app could not write to Supabase, usually because the service key is missing or the database grants are incomplete.

Fix:

• Set NEXT_PUBLIC_SUPABASE_URL.
• Set NEXT_PUBLIC_SUPABASE_ANON_KEY.
• Set SUPABASE_SERVICE_ROLE_KEY for server-side writes.
• Apply the updated grants in supabase/schema.sql.

Dashboard does not launch

Symptoms: autopilot dashboard exits immediately or fails in CI.

Cause: The dashboard requires a TTY unless test mode is enabled.

Fix:

• Run it in an interactive terminal.
• In tests, set AUTOPILOT_TEST_MODE=1.

Autopilot is too noisy in a large repo

Symptoms: Lots of change detections and slow response on large workspaces.

Fix:

• Add generated directories to .autopilotignore.
• Keep your watch path scoped to the real source tree.
• Increase the debounce window if needed.

Debugging Tools

Manual Git Check

Autopilot relies on git status to detect changes. You can see exactly what Autopilot sees by running:

git status --porcelain

If this command returns nothing, Autopilot assumes there is nothing to commit.

Log Files

Autopilot writes detailed logs to autopilot.log in your project root. This file contains timestamps of every detection, commit, and error.

tail -f autopilot.log

Reviewing the last few lines of this file often reveals the exact error message from Git or the system.