Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
189 lines (135 loc) · 10.5 KB

TROUBLESHOOTING.md

File metadata and controls

189 lines (135 loc) · 10.5 KB

Troubleshooting gac

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

This guide covers common issues and solutions for installing, configuring, and running gac.

Table of Contents

1. Setup Problems

Problem: uvx command not found

  • Install uv by following the instructions at astral.sh/uv
  • Make sure uv is installed and in your $PATH
  • Restart your terminal after installation

2. Configuration Issues

Problem: gac can't find your API key or model

  • If you are new, run uvx gac init to interactively set up your provider, model, and API keys
  • Make sure your .gac.env or environment variables are set correctly
  • Run uvx gac --log-level=debug to see which config files are loaded and debug configuration issues
  • Check for typos in variable names (e.g., GAC_GROQ_API_KEY)

Problem: User-level $HOME/.gac.env changes are not picked up

  • Make sure you are editing the correct file for your OS:
    • On macOS/Linux: $HOME/.gac.env (usually /Users/<your-username>/.gac.env or /home/<your-username>/.gac.env)
    • On Windows: $HOME/.gac.env (typically C:\Users\<your-username>\.gac.env or use %USERPROFILE%)
  • Run uvx gac --log-level=debug to confirm the user-level config is loaded
  • Restart your terminal or re-run your shell to reload environment variables
  • If still not working, check for typos and file permissions

Problem: Project-level .gac.env changes are not picked up

  • Ensure your project contains a .gac.env file in the root directory (next to your .git folder)
  • Run uvx gac --log-level=debug to confirm the project-level config is loaded
  • If you edit .gac.env, restart your terminal or re-run your shell to reload environment variables
  • If still not working, check for typos and file permissions

Problem: Cannot set or change language for commit messages

  • Run uvx gac language (or uvx gac lang) to interactively select from 25+ supported languages
  • Use -l <language> flag to override language for a single commit (e.g., uvx gac -l zh-CN, uvx gac -l Spanish)
  • Check your config with uvx gac config show to see current language setting
  • Language setting is stored in GAC_LANGUAGE in your .gac.env file

3. Provider/API Errors

Problem: Authentication or API errors

  • Ensure you have set the correct API keys for your chosen model (e.g., ANTHROPIC_API_KEY, GROQ_API_KEY)
  • Double-check your API key and provider account status
  • For Ollama and LM Studio, confirm the API URL matches your local instance. API keys are only needed if you enabled authentication.
  • For Claude Code token expiration: Run uvx gac auth to quickly re-authenticate and refresh your token. Your browser will open automatically for OAuth.
  • For ChatGPT OAuth token expiration: Run uvx gac auth chatgpt login to re-authenticate. Your browser will open automatically for OAuth.
  • For GitHub Copilot session issues: Run uvx gac auth copilot login to re-authenticate via Device Flow. Session tokens auto-refresh from the cached OAuth token.
  • For other Claude Code OAuth issues, see the Claude Code setup guide for comprehensive troubleshooting.
  • For other ChatGPT OAuth issues, see the ChatGPT OAuth setup guide for comprehensive troubleshooting.
  • For other Copilot issues, see the GitHub Copilot setup guide for comprehensive troubleshooting.

Problem: Model not available or unsupported

  • Streamlake uses inference endpoint IDs instead of model names. Make sure you supply the endpoint ID from their console.
  • Verify the model name is correct and supported by your provider
  • Check provider documentation for available models

4. Commit Grouping Issues

Problem: --group flag not working as expected

  • The --group flag automatically analyzes staged changes and can create multiple logical commits
  • The LLM may decide that a single commit makes sense for your set of staged changes, even with --group
  • This is intentional behavior - the LLM groups changes based on logical relationships, not just quantity
  • Ensure you have multiple unrelated changes staged (e.g., bug fix + feature addition) for best results
  • Use uvx gac --show-prompt to debug what the LLM is seeing

Problem: Commits grouped incorrectly or not grouped when expected

  • The grouping is determined by the LLM's analysis of your changes
  • The LLM may create a single commit if it determines the changes are logically related
  • Try adding hints with -h "hint" to guide the grouping logic (e.g., -h "separate bug fix from refactoring")
  • Review the generated groups before confirming
  • If grouping doesn't work well for your use case, commit changes separately instead

5. Security and Secret Detection

Important: Secret scanning runs before any AI API call is made. If a secret is detected, the workflow aborts immediately and no API call occurs. The scanner uses regex-based pattern matching (not LLMs), so scanning is fast and runs entirely locally — your code is never sent to an AI model for secret detection.

Problem: False positive: secret scan detects non-secrets

  • The security scanner uses regex patterns to look for strings that resemble API keys, tokens, and passwords
  • If you're committing example code, test fixtures, or documentation with placeholder keys, you may see false positives
  • Use --skip-secret-scan to bypass the scan if you're certain the changes are safe
  • Consider excluding test/example files from commits, or use clearly marked placeholders

Problem: Secret scan not detecting actual secrets

  • The scanner uses regex-based pattern matching (not LLMs) and may not catch all secret types
  • Always review your staged changes with git diff --staged before committing
  • Consider using additional security tools like git-secrets or gitleaks for comprehensive protection
  • Report any missed patterns as issues to help improve detection

Problem: Need to disable secret scanning permanently

  • Set GAC_SKIP_SECRET_SCAN=true in your .gac.env file
  • Use uvx gac config set GAC_SKIP_SECRET_SCAN true
  • Note: Only disable if you have other security measures in place

6. Pre-commit and Lefthook Hook Issues

Problem: Pre-commit or lefthook hooks are failing and blocking commits

  • Use uvx gac --no-verify to skip all pre-commit and lefthook hooks temporarily
  • Fix the underlying issues causing the hooks to fail
  • Consider adjusting your pre-commit or lefthook configuration if hooks are too strict

Problem: Pre-commit or lefthook hooks take too long or are interfering with workflow

  • Use uvx gac --no-verify to skip all pre-commit and lefthook hooks temporarily
  • Consider configuring pre-commit hooks in .pre-commit-config.yaml or lefthook hooks in .lefthook.yml to be less aggressive for your workflow
  • Review your hook configuration to optimize performance

7. Common Workflow Issues

Problem: No changes to commit / nothing staged

  • gac requires staged changes to generate a commit message
  • Use git add <files> to stage changes, or use uvx gac -a to stage all changes automatically
  • Check git status to see what files have been modified
  • Use uvx gac diff to see a filtered view of your changes

Problem: Commit message not what I expected

  • Use the interactive feedback system: type r to reroll, e to edit (in-place TUI, or external editor via GAC_EDITOR), or provide natural language feedback
  • Add context with -h "your hint" to guide the LLM
  • Use -o for simpler one-line messages or -v for more detailed messages
  • Use --show-prompt to see what information the LLM is receiving

Problem: gac is too slow

  • Use uvx gac -y to skip the confirmation prompt
  • Use uvx gac -q for quiet mode with less output
  • Consider using faster/cheaper models for routine commits
  • Use uvx gac --no-verify to skip hooks if they're slowing you down

Problem: Can't edit or provide feedback after message generation

  • At the prompt, type e to enter edit mode (in-place TUI with vi/emacs keybindings; set GAC_EDITOR to use your preferred editor instead)
  • Type r to regenerate without feedback
  • Or simply type your feedback directly (e.g., "make it shorter", "focus on the bug fix")
  • Press Enter on empty input to see the prompt again

8. General Debugging

  • Use uvx gac init to reset or update your configuration interactively
  • Use uvx gac --log-level=debug for detailed debug output and logging
  • Use uvx gac --show-prompt to see what prompt is being sent to the LLM
  • Use uvx gac --help to see all available command-line flags
  • Use uvx gac config show to see all current configuration values
  • Check logs for error messages and stack traces
  • Check the main README.md for features, examples, and quick start instructions

Still Stuck?

  • Search existing issues or open a new one on the GitHub repository
  • Include details about your OS, Python version, gac version, provider, and error output
  • The more detail you provide, the faster your issue can be resolved

Where to Get Further Help