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

Feilsøking av gac

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

Denne guiden dekker vanlige problemer og løsninger for installasjon, konfigurasjon og kjøring av gac.

Table of Contents

1. Oppsettsproblemer

Problem: uvx-kommando ikke funnet

  • Installer uv ved å følge instruksjonene på astral.sh/uv
  • Sørg for at uv er installert og i din $PATH
  • Start terminalen på nytt etter installasjon

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-utløp: Kjør uvx gac auth for raskt å autentisere på nytt og oppdatere tokenet ditt. Nettleseren åpnes automatisk for OAuth.
  • For ChatGPT OAuth token-utløp: Kjør uvx gac auth chatgpt login for å autentisere på nytt. Nettleseren åpnes automatisk for OAuth.
  • For andre Claude Code OAuth-problemer, se Claude Code oppsettguide for omfattende feilsøking.
  • For andre ChatGPT OAuth-problemer, se ChatGPT OAuth oppsettguide for omfattende feilsøking.
  • For utløpte GitHub Copilot-økttokens: Kjør uvx gac auth copilot login for å re-autentisere via Device Flow. Økttokens fornyes automatisk fra den bufrede OAuth-tokenen.
  • For andre GitHub Copilot-problemer, se GitHub Copilot-oppsettsguiden for omfattende feilsøking.

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 looks for regex patterns 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

  • Bruk det interaktive feedbacksystemet: skriv r for reroll, e for å redigere (innebygd TUI, eller ekstern editor via GAC_EDITOR), eller gi feedback på naturlig språk
  • 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

  • Ved prompten, skriv e for å gå inn i redigeringsmodus (innebygd TUI med vi/emacs-tastebindinger; sett GAC_EDITOR for å bruke din foretrukne editor i stedet)
  • 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