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:

gitaiflow --help

Verify the installed version:

gitaiflow --version

Check telemetry state if relevant:

gitaiflow --telemetry status

Then run a small summary against the repository:

gitaiflow --path .

If the command succeeds, inspect the generated artifact under:

change-summary/<YYYY>/<MM>/<DD>/

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:

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:

command not found: gitaiflow

or, on macOS, Gatekeeper blocking an unsigned downloaded binary:

"gitaiflow" cannot be opened because the developer cannot be verified.

#Checks

Verify the executable is on PATH:

which gitaiflow

On Windows:

Get-Command gitaiflow

Verify the binary itself is intact and executable:

ls -la /usr/local/bin/gitaiflow
file /usr/local/bin/gitaiflow

#Resolution

command not found: re-run the installer (see ../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:

xattr -d com.apple.quarantine /usr/local/bin/gitaiflow

Or allow it via System Settings → Privacy & Security → Allow Anyway on first run.

Then verify:

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:

git rev-parse --show-toplevel

Check repository status:

git status --short

Check the current branch:

git branch --show-current

#Resolution

Run gitaiflow from a Git working tree or explicitly point it at the intended target:

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:

git status --short

Compare the working tree against the expected base:

git diff

Check the base branch/reference if the run uses one:

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:

echo "$AI_PROVIDER"
echo "$AI_MODEL"
echo "$AI_BASE_URL"

Do not print:

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:

AI_PROVIDER=<provider>
AI_API_KEY=<secret>
AI_BASE_URL=<endpoint>
AI_MODEL=<model>

Then rerun:

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:

echo "$AI_MODEL"

For OpenRouter model discovery:

gitaiflow --list-models

If using a local provider, verify the model is installed and available through that provider.

#Resolution

Set a valid model:

export AI_MODEL=<valid-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:

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:

ollama list

#Resolution

Correct the endpoint or start the local provider service.

Then retry:

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:

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:

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:

~/.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:

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:

git status --short

Inspect the generated diff artifacts under:

change-summary/<YYYY>/<MM>/<DD>/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:

.env
.certs
change-summary

and sensitive key names such as:

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:

change-summary/<YYYY>/<MM>/<DD>/

Expected directories include:

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:

pwd

Check repository root:

git rev-parse --show-toplevel

Then locate recent artifacts:

find change-summary -type f -mtime -1

On Windows 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:

gitaiflow --telemetry status

Disable it:

gitaiflow --telemetry disable

Enable it:

gitaiflow --telemetry enable

View consent history:

gitaiflow --telemetry history

For one run only:

GITAIFLOW_TELEMETRY=false gitaiflow --path .

or:

GITAIFLOW_TELEMETRY=true gitaiflow --path .

Telemetry failures should not fail the primary gitaiflow operation.

For detailed telemetry behavior, see:

user-guides/telemetry.md

17. CI/CD Troubleshooting

For CI, make the important configuration explicit.

Recommended pattern:

GITAIFLOW_TELEMETRY=false gitaiflow --path .

or, if your organization intentionally enables telemetry:

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:

env

when the output could expose secrets.

18. Changelog Troubleshooting

Changelog generation is a separate execution path.

Example:

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:

git log --oneline

Verify the selected date range and base/remote reference.

Check whether expected JSON artifacts exist under:

change-summary/<YYYY>/<MM>/<DD>/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:

ls -ld .
ls -ld change-summary 2>/dev/null

Check the local gitaiflow directory:

ls -la ~/.gitaiflow 2>/dev/null

Check:

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:

Current process environment
        ↓
Repository / discovered .env configuration
        ↓
Application defaults

For telemetry specifically:

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:

gitaiflow --version
python --version
git --version

Then record non-secret configuration:

echo "$AI_PROVIDER"
echo "$AI_BASE_URL"
echo "$AI_MODEL"

Do not include:

AI_API_KEY

or any other secret.

Also capture:

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

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:

gitaiflow --version
python --version
git --version

and the non-sensitive configuration:

echo "$AI_PROVIDER"
echo "$AI_BASE_URL"
echo "$AI_MODEL"

Then provide:

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.