Troubleshooting

Common issues and how to fix them.

”command not found: fledge”

fledge isn’t on your PATH. If you installed via cargo install:

# Make sure ~/.cargo/bin is on your PATH
export PATH="$HOME/.cargo/bin:$PATH"

Add that line to your .bashrc, .zshrc, or shell profile. Then restart your terminal or run source ~/.zshrc.

GitHub commands fail with “no token”

Commands that talk to GitHub need a GitHub personal access token. In core: review, templates search, templates publish, lanes search, lanes publish, plugins search, plugins publish. From fledge-plugin-github (after fledge plugins install --defaults): github checks, github issues, github prs.

# Easiest: use the GitHub CLI (zero config)
gh auth login

# Or set it as an environment variable
export GITHUB_TOKEN="ghp_..."

# Or store it in fledge config
fledge config set github.token "ghp_..."

The token needs repo scope for private repos, or just public_repo for public ones. If you have gh installed and authenticated, fledge uses it automatically as a fallback.

”no template found” when running init

Check what’s available:

fledge templates list

If you expect remote templates, make sure the repo is configured:

fledge config add templates.repos "CorvidLabs/fledge-templates"

Or use the full path:

fledge templates init my-app --template CorvidLabs/fledge-templates/python-api

Tasks not detected (fledge run shows nothing)

fledge auto-detects your project type from marker files. If it doesn’t find anything:

  1. Make sure you’re in the project root (where Cargo.toml, package.json, etc. live)
  2. Run fledge doctor to check your environment
  3. If auto-detection doesn’t fit, create a fledge.toml manually:
fledge run --init

Template hooks won’t run

Remote template hooks require confirmation for security. If you trust the template:

fledge templates init my-app --template user/repo --yes

If hooks fail after confirmation, check that the required tools are installed (e.g., npm, pip, cargo fmt).

“rate limit exceeded” from GitHub

GitHub’s API has rate limits. Authenticated requests get 5,000/hour vs 60/hour for unauthenticated.

# Set your token to get higher limits
export GITHUB_TOKEN="ghp_..."

Cached templates are stale

Templates from remote repos are cached locally. To force a fresh download:

fledge templates init my-app --template user/repo --refresh

fledge review / fledge ask not working

These commands use the active AI provider. Check which provider is configured:

fledge ai status
fledge doctor        # the AI section will diagnose the issue

If using Claude (default): Make sure the claude CLI is installed and authenticated:

claude --version

If Claude isn’t installed, see Claude CLI docs for setup instructions.

If using Ollama: Make sure the Ollama daemon is running and the host is correct:

fledge ai status                    # check host and model
fledge ai models --provider ollama  # verify the endpoint is reachable

If the host is missing http://, fledge normalizes it automatically. If using Ollama Cloud, make sure OLLAMA_API_KEY or ai.ollama.api_key is set.

Clippy or fmt warnings in CI

Run these locally before pushing:

cargo clippy -- -D warnings
cargo fmt --check

If clippy finds issues, fix them. If formatting is off, run cargo fmt (without --check) to auto-fix.

Still stuck?

  1. Run fledge doctor for a full environment check
  2. Check GitHub Issues for known problems
  3. Open a new issue with:
    • Your OS and fledge version (fledge --version)
    • The command you ran
    • The full error output