--- since: 1.1.1 --- # Troubleshooting This runbook is for diagnosing and resolving common gitaiflow operational problems in local development, CI/CD, and automated environments. It is intentionally task-oriented: start with the symptom, verify the relevant state, apply the smallest corrective action, and rerun the command. --- ## 1. Quick Health Check Start with: ```bash gitaiflow --help ``` Verify the installed version: ```bash gitaiflow --version ``` Check telemetry state if relevant: ```bash gitaiflow --telemetry status ``` Then run a small summary against the repository: ```bash gitaiflow --path . ``` If the command succeeds, inspect the generated artifact under: ```text change-summary///
/ ``` A normal run should produce the expected JSON artifact and, when requested, Markdown output. --- # 2. Standard Diagnostic Sequence When a run fails, use this order: ```text 1. Verify gitaiflow installation ↓ 2. Verify Git repository / target ↓ 3. Verify AI configuration ↓ 4. Verify provider connectivity ↓ 5. Verify diff generation ↓ 6. Inspect generated artifacts ↓ 7. Check local usage / telemetry only if relevant ``` Avoid changing multiple configuration values at once. Establish which layer is failing first. --- # 3. Command Fails Immediately ## Symptoms Examples: ```text command not found: gitaiflow ``` or, on macOS, Gatekeeper blocking an unsigned downloaded binary: ```text "gitaiflow" cannot be opened because the developer cannot be verified. ``` ## Checks Verify the executable is on `PATH`: ```bash which gitaiflow ``` On Windows: ```powershell Get-Command gitaiflow ``` Verify the binary itself is intact and executable: ```bash ls -la /usr/local/bin/gitaiflow file /usr/local/bin/gitaiflow ``` ## Resolution **`command not found`:** re-run the installer (see [`../user-guide/installation.md`](../user-guide/installation.md)) — it places the binary on `PATH` automatically. If you compiled locally, either add `./bin/` to `PATH` for the session or copy the binary to `/usr/local/bin/gitaiflow`. **macOS Gatekeeper block:** the compiled binary isn't notarized/code-signed by Apple, so a `curl`-downloaded binary gets quarantined: ```bash xattr -d com.apple.quarantine /usr/local/bin/gitaiflow ``` Or allow it via **System Settings → Privacy & Security → Allow Anyway** on first run. Then verify: ```bash gitaiflow --version ``` --- # 4. Target Is Not a Git Repository ## Symptoms The command cannot determine repository information, the Git root, changed files, or the requested base reference. ## Checks From the target directory: ```bash git rev-parse --show-toplevel ``` Check repository status: ```bash git status --short ``` Check the current branch: ```bash git branch --show-current ``` ## Resolution Run gitaiflow from a Git working tree or explicitly point it at the intended target: ```bash gitaiflow --path /path/to/repository ``` If the path is a file, ensure the file belongs to a Git repository that gitaiflow can discover. --- # 5. No Changes Detected ## Symptoms gitaiflow reports that there are no changes to summarize. ## Checks Inspect Git status: ```bash git status --short ``` Compare the working tree against the expected base: ```bash git diff ``` Check the base branch/reference if the run uses one: ```bash git branch --show-current git remote -v ``` ## Resolution Make sure the intended changes are visible to Git and that the selected target/base configuration matches the workflow you expect. Remember that gitaiflow operates on the Git changes it can discover; it cannot summarize changes that are outside the selected Git comparison. --- # 6. AI Configuration Errors ## Symptoms Typical causes include: - missing API key - missing model - invalid provider - invalid base URL - incomplete provider configuration ## Checks Inspect your environment without printing secrets: ```bash echo "$AI_PROVIDER" echo "$AI_MODEL" echo "$AI_BASE_URL" ``` Do **not** print: ```bash echo "$AI_API_KEY" ``` or any other credential into logs. Check whether a repository-local `.env` is being used and whether the required values are present. ## Resolution Configure the required AI settings through environment variables or the supported `.env` configuration. Typical configuration: ```text AI_PROVIDER= AI_API_KEY= AI_BASE_URL= AI_MODEL= ``` Then rerun: ```bash gitaiflow --path . ``` If the provider uses a local endpoint such as Ollama, verify that the endpoint and model are available locally. --- # 7. Invalid or Unavailable AI Model ## Symptoms The provider responds with an error indicating that: - the model does not exist - the model is unavailable - the model is not supported - the model identifier is invalid ## Checks Verify the configured model: ```bash echo "$AI_MODEL" ``` For OpenRouter model discovery: ```bash gitaiflow --list-models ``` If using a local provider, verify the model is installed and available through that provider. ## Resolution Set a valid model: ```bash export AI_MODEL= ``` Then rerun the summary. Do not assume that a model name valid for one provider is valid for another. --- # 8. AI Provider Connection Failure ## Symptoms The request fails because the AI endpoint cannot be reached. Possible causes: - endpoint is incorrect - provider is unavailable - DNS failure - network restriction - proxy/firewall configuration - local AI server is not running ## Checks Verify the configured endpoint: ```bash echo "$AI_BASE_URL" ``` Do not include API credentials when sharing diagnostic output. For local providers, verify the service is running. For example, with Ollama: ```bash ollama list ``` ## Resolution Correct the endpoint or start the local provider service. Then retry: ```bash gitaiflow --path . ``` If the provider is external, verify network access from the same environment where gitaiflow runs. --- # 9. Authentication Failure ## Symptoms The AI provider returns an authentication or authorization error, commonly HTTP `401` or `403`. ## Checks Verify that the API key variable exists without printing its value: ```bash test -n "$AI_API_KEY" && echo "AI_API_KEY is set" || echo "AI_API_KEY is not set" ``` Check that the key belongs to the configured provider. Check: ```bash echo "$AI_PROVIDER" echo "$AI_BASE_URL" echo "$AI_MODEL" ``` ## Resolution Replace an expired, revoked, or incorrect credential. Do not put credentials into: - source code - Git commits - issue reports - generated documentation - shell history when avoidable - telemetry payloads --- # 10. Rate Limit or Provider Quota ## Symptoms The provider rejects the request because of: - rate limits - token limits - account quota - billing limits ## Checks Inspect the provider's response and account status. Also inspect the local usage record: ```text ~/.gitaiflow/usage.jsonl ``` The local usage record can help identify: - number of runs - estimated token usage - provider/model - duration - success/failure ## Resolution Use the provider's supported quota controls, wait for the rate limit window, reduce request size, or select an appropriate model/provider. gitaiflow's local daily limits are courtesy guardrails; they are not a replacement for provider-side quotas. Example: ```bash export GITAIFLOW_MAX_RUNS_PER_DAY=20 export GITAIFLOW_MAX_TOKENS_PER_DAY=50000 ``` --- # 11. Diff Is Too Large ## Symptoms The AI provider rejects the request because the prompt exceeds the model context window, or the request becomes impractical to process. ## Checks Inspect the changed-file count: ```bash git status --short ``` Inspect the generated diff artifacts under: ```text change-summary///
/diff/ ``` Check whether the change includes: - large generated files - vendor/package directories - minified assets - binary files - unrelated changes ## Resolution Reduce the scope of the target or exclude unnecessary files according to the gitaiflow configuration. Do not solve a context-window problem by exposing sensitive data that should have been excluded. For very large changes, generate summaries for smaller logical units where appropriate. --- # 12. Sensitive Data Appears in the Diff ## Symptoms A generated diff contains a credential, secret, token, certificate, or other sensitive value that should not be sent to the AI provider. ## Immediate Action **Do not continue with the AI request.** Review the generated diff artifact before rerunning. The implementation provides best-effort exclusions and redaction, but it is not a complete secret scanner. ## Checks Look for: ```text .env .certs change-summary ``` and sensitive key names such as: ```text SECRET_KEY API_KEY PRIVATE_KEY ACCESS_KEY CLIENT_SECRET ``` ## Resolution Remove the sensitive content from the change being analyzed, add the appropriate exclusion/redaction rule where supported, or otherwise reduce the target before rerunning. If a real credential was exposed to a cloud provider, treat it as compromised and rotate/revoke it according to the credential owner's security procedure. --- # 13. Generated Artifacts Are Missing ## Symptoms The command completes but the expected files cannot be found. ## Checks Look under: ```text change-summary///
/ ``` Expected directories include: ```text diff/ json/ markdown/ ``` Markdown is only produced when requested. ## Resolution Check that the command is operating against the repository you expect and that the process has write permission to the workspace. Check the current working directory: ```bash pwd ``` Check repository root: ```bash git rev-parse --show-toplevel ``` Then locate recent artifacts: ```bash find change-summary -type f -mtime -1 ``` On Windows PowerShell: ```powershell Get-ChildItem -Recurse change-summary ``` --- # 14. JSON Exists but Markdown Does Not This is normally expected when Markdown output was not requested. The canonical output is JSON. Markdown is a derived human-readable representation and is optional. If you need Markdown, rerun using the Markdown option supported by the installed gitaiflow version. --- # 15. Commit Output Is Unexpected ## Symptoms The generated title/body is incomplete, malformed, or not in the expected structure. ## Checks Inspect the raw generated JSON artifact. The normal parser expects the model response to contain the expected title/body structure. Verify the configured model and prompt configuration. ## Resolution Retry the run with the same Git target. If the issue is consistently reproducible with the same provider/model, compare the behavior against another supported model or provider. Do not manually modify the canonical JSON merely to hide a reproducible generation problem; preserve the artifact when investigating. --- # 16. Telemetry Issues Telemetry is separate from AI summary generation. Check the current state: ```bash gitaiflow --telemetry status ``` Disable it: ```bash gitaiflow --telemetry disable ``` Enable it: ```bash gitaiflow --telemetry enable ``` View consent history: ```bash gitaiflow --telemetry history ``` For one run only: ```bash GITAIFLOW_TELEMETRY=false gitaiflow --path . ``` or: ```bash GITAIFLOW_TELEMETRY=true gitaiflow --path . ``` Telemetry failures should not fail the primary gitaiflow operation. For detailed telemetry behavior, see: ```text user-guides/telemetry.md ``` --- # 17. CI/CD Troubleshooting For CI, make the important configuration explicit. Recommended pattern: ```bash GITAIFLOW_TELEMETRY=false gitaiflow --path . ``` or, if your organization intentionally enables telemetry: ```bash GITAIFLOW_TELEMETRY=true gitaiflow --path . ``` Verify: - gitaiflow is installed in the CI environment - Git history required by the selected operation is available - the target path is correct - provider credentials are configured as CI secrets - the model and endpoint are available - the runner can reach the provider - generated artifacts have an appropriate destination - telemetry behavior is explicitly configured Never print API credentials during CI diagnostics. Avoid commands such as: ```bash env ``` when the output could expose secrets. --- # 18. Changelog Troubleshooting Changelog generation is a separate execution path. Example: ```bash gitaiflow --changelog --since 2026/08/01 --path . ``` It can use existing change-summary JSON artifacts and can fall back to Git history. ## If no changes appear Check: ```bash git log --oneline ``` Verify the selected date range and base/remote reference. Check whether expected JSON artifacts exist under: ```text change-summary///
/json/ ``` ## If remote history is unavailable Fetch the required repository history/reference before retrying. For CI environments using shallow clones, ensure the history required by the changelog operation is available. Changelog generation does not require an AI provider. --- # 19. File Permissions ## Symptoms gitaiflow cannot create or update: - `change-summary` - local usage files - telemetry consent files - install ID ## Checks Check the workspace: ```bash ls -ld . ls -ld change-summary 2>/dev/null ``` Check the local gitaiflow directory: ```bash ls -la ~/.gitaiflow 2>/dev/null ``` Check: ```bash ls -la ~/.gitaiflow_telemetry_consent 2>/dev/null ``` ## Resolution Run gitaiflow as the user who owns the working directory whenever possible. Avoid running gitaiflow with `sudo` merely to bypass a permissions problem. Correct the underlying ownership or permissions instead. --- # 20. Environment Configuration Problems A common source of confusion is mixing persistent shell configuration, repository `.env` configuration, and one-command environment overrides. Use this hierarchy when diagnosing: ```text Current process environment ↓ Repository / discovered .env configuration ↓ Application defaults ``` For telemetry specifically: ```text GITAIFLOW_TELEMETRY ↓ Saved telemetry consent ↓ Default: disabled ``` Therefore an environment-variable override can change behavior for one command without changing the saved telemetry decision. --- # 21. Clean Reproduction When reporting a reproducible problem, reduce it to the smallest repository state possible. Capture: ```bash gitaiflow --version python --version git --version ``` Then record non-secret configuration: ```bash echo "$AI_PROVIDER" echo "$AI_BASE_URL" echo "$AI_MODEL" ``` Do not include: ```text AI_API_KEY ``` or any other secret. Also capture: ```bash git status --short git branch --show-current git rev-parse --show-toplevel ``` If appropriate, preserve the generated JSON and relevant error output. Do not attach: - API keys - `.env` files - unredacted sensitive diffs - private credentials - certificates/private keys --- # 22. Safe Diagnostic Checklist Before sharing a gitaiflow failure with maintainers: - [ ] gitaiflow version captured - [ ] Python version captured - [ ] Git version captured - [ ] provider identified - [ ] model identified - [ ] endpoint identified without credentials - [ ] target type identified - [ ] Git status checked - [ ] Git branch checked - [ ] error message captured - [ ] generated artifact inspected - [ ] secrets removed from logs - [ ] `.env` excluded - [ ] API keys removed - [ ] private repository information removed where necessary --- # 23. Common Recovery Matrix | Symptom | First check | Typical action | |---|---|---| | `gitaiflow` not found | `which gitaiflow` | Re-run the installer / add binary to `PATH` | | Not a Git repository | `git rev-parse --show-toplevel` | Use correct repository path | | No changes | `git status --short` | Verify target/base comparison | | Missing API configuration | `AI_PROVIDER`, `AI_MODEL`, `AI_BASE_URL` | Configure provider | | `401` / `403` | Credential presence/provider | Replace or correct credential | | Model not found | `AI_MODEL` / `--list-models` | Select valid model | | Connection failure | `AI_BASE_URL` / provider service | Correct endpoint or start service | | Rate limited | Provider response / local usage | Wait, reduce usage, or change model/provider | | Context too large | Generated diff size | Reduce scope/exclude unnecessary files | | Sensitive data in diff | `diff/` artifact | Stop, remove/redact, rotate exposed secrets if necessary | | Missing Markdown | Output options | Request Markdown explicitly | | Telemetry concern | `gitaiflow --telemetry status` | Disable telemetry | | Changelog incomplete | Git history / JSON artifacts | Verify date range and available history | | Permission denied | File ownership/permissions | Fix ownership/permissions; avoid `sudo` | --- # 24. Operational Principles When operating gitaiflow: 1. **Treat the generated diff as sensitive.** Best-effort redaction does not guarantee that every secret will be detected. 2. **Never expose credentials in diagnostics.** 3. **Keep provider configuration explicit in CI.** 4. **Use local AI providers when repository data must remain local.** 5. **Treat telemetry and AI-provider traffic as separate concerns.** 6. **Use the canonical JSON artifact when investigating a completed run.** 7. **Prefer fixing the underlying configuration or permission issue instead of using elevated privileges.** 8. **Preserve the original error when escalating an issue.** 9. **Reduce the reproduction before changing multiple variables.** 10. **Do not assume provider-specific model names, endpoints, limits, or authentication rules are interchangeable.** --- # 25. Escalation If the problem persists after following the relevant procedure, collect: ```bash gitaiflow --version python --version git --version ``` and the non-sensitive configuration: ```bash echo "$AI_PROVIDER" echo "$AI_BASE_URL" echo "$AI_MODEL" ``` Then provide: ```bash git status --short git branch --show-current ``` along with: - the exact command used - the exact error message - the relevant JSON artifact, if safe to share - whether the failure is reproducible - whether the failure occurs with another model/provider - whether the failure occurs locally and/or in CI **Never include API keys, `.env` contents, private keys, or unredacted proprietary diffs in an issue or support request.**