Troubleshooting

This page covers the most common failure modes encountered when running ai-commit, including the specific exception types raised, their root causes, and how to resolve them. It also describes the diagnostic flags available on the commit command.

For background on the command itself see page 3.1 (Commit Command Workflow), for configuration setup see page 3.3 (Configuration Management), and for generator-specific configuration values see page 7.4 (Generator-Specific Configuration).

---

Error Taxonomy

The diagram below maps common runtime failures to the exception classes and the stage in the commit workflow where they occur.

Failure points in the commit workflow

Sources: tests/Feature/CommitCommandTest.php34-54 app/Exceptions/RuntimeException.php app/Exceptions/UnsupportedConfigFileTypeException.php app/Exceptions/UnsupportedConfigActionException.php

---

Common Failures

1. Not a Git Repository

Exception: Symfony\Component\Process\Exception\ProcessFailedException

Symptom: The command exits immediately with output containing fatal: from git.

Cause: The path argument (or the working directory) is not inside a git repository. The CommitCommand calls git diff via a Process; when git cannot find a repository, the process exits non-zero, which causes mustRun() to throw ProcessFailedException.

Resolution:

• Run ai-commit commit from inside a git repository, or pass the correct path:

• Confirm the directory is a repository: git rev-parse --show-toplevel

Sources: tests/Feature/CommitCommandTest.php34-41

---

2. No Staged Files

Exception: App\Exceptions\RuntimeException

Message: There are no cached files to commit. Try running 'git add' to cache some files.

Cause: git diff --cached returned empty output. The commit command checks for staged content before calling the AI generator. If nothing is staged, it raises App\Exceptions\RuntimeException immediately.

Resolution:

Then re-run ai-commit commit.

Sources: tests/Feature/CommitCommandTest.php43-54 app/Exceptions/RuntimeException.php

---

3. API Authentication Errors

Exception: Illuminate\Http\Client\RequestException

Symptom: HTTP status code 401 (Unauthorized) or 403 (Forbidden) printed to stderr. The command aborts after exhausting configured retry attempts.

Cause: The API key configured for the generator is missing, expired, or invalid.

Generator	Config key	Example error payload
openai / openai_chat	generators.openai.api_key	{"error":{"message":"Incorrect API key provided...","code":"invalid_api_key"}}
moonshot	generators.moonshot.api_key	{"error":{"message":"auth failed","type":"invalid_authentication_error"}}
ernie_bot / ernie_bot_turbo	generators.ernie_bot.api_key + secret_key	{"error_code":17,"error_msg":"Open api daily request limit reached"}

Resolution:

Set the correct API key using the config set sub-command:

Verify the stored value:

Sources: tests/Unit/Generators/OpenAIGeneratorTest.php37-46 tests/Unit/Generators/MoonshotGeneratorTest.php38-47 tests/Pest.php112-215

---

4. CLI Generator Binary Not Found

Exception: Symfony\Component\Process\Exception\ProcessFailedException

Symptom: The command fails with a message that the binary (bito, gh, etc.) could not be found or executed.

Cause: CLI-based generators (bito_cli, github_copilot_cli, github_models_cli) shell out to an external binary. If that binary is not on PATH or the configured path is wrong, the Process will fail.

Resolution:

Configure the binary path explicitly:

Verify the binary is executable:

Sources: README.md61-68

---

5. Unsupported Config File Type

Exception: App\Exceptions\UnsupportedConfigFileTypeException

Message: The config file type [<ext>] is not supported

Cause: A file path passed to --config or used by ConfigManager has an extension that is not recognized (only .json is supported for local/global config files). The UnsupportedConfigFileTypeException::make() factory includes the offending extension in the message.

Resolution:

Ensure any custom config file has a .json extension:

The default file names used by the system are:

• Local: .ai-commit.json (in the working directory)
• Global: ~/.ai-commit/.ai-commit.json

Sources: app/Exceptions/UnsupportedConfigFileTypeException.php

---

6. Unsupported Config Action

Exception: App\Exceptions\UnsupportedConfigActionException

Message: The action [<action>] is not supported, that must be one of [set, get, unset, reset, list, edit].

Cause: The first argument passed to ai-commit config is not one of the recognized action names.

Resolution:

Use one of the valid actions:

Sources: app/Exceptions/UnsupportedConfigActionException.php

---

Diagnostic Tools

--dry-run

Generates a commit message but does not execute git commit. Useful for validating that the generator, API key, and prompt configuration are all working before touching git history.

--verbose / -v|vv|vvv

Increases output verbosity. At the highest level (-vvv), the command prints process invocations (RUN), standard output (OUT), and standard error (ERR) from child processes, which is essential for debugging CLI-based generators.

Example verbose output from a bito_cli run:

 RUN 'bito'
 ERR Model in use: BASIC
 OUT {"subject": "chore(...): ...", "body": "..."}
 RES Command ran successfully

--diff

Allows manually supplying the diff content as a string, bypassing git diff entirely. This is useful when:

• The diff is too large or unusual for the default git invocation.
• You want to test a specific prompt without staging actual changes.

--retry-times and --retry-sleep

Control how many times the generator retries on transient API errors and the delay between retries (in milliseconds). Defaults are 3 retries with 200 ms sleep.

Sources: README.md219-236

---

Diagnostic Decision Flow

How to approach a failure

Sources: tests/Feature/CommitCommandTest.php34-54 tests/Unit/Generators/OpenAIGeneratorTest.php37-46 app/Exceptions/UnsupportedConfigFileTypeException.php app/Exceptions/RuntimeException.php

---

Quick Reference

Symptom	Exception Class	Resolution
fatal: not a git repository	ProcessFailedException	Run inside a git repo or fix the path argument
There are no cached files to commit	App\Exceptions\RuntimeException	git add files before committing
HTTP request returned status code 401	Illuminate\Http\Client\RequestException	Fix API key via config set
HTTP request returned status code 403	Illuminate\Http\Client\RequestException	Check API key permissions / quota
Binary not found (bito, gh)	ProcessFailedException	Set generators.<name>.binary config
config file type [...] is not supported	UnsupportedConfigFileTypeException	Use a .json config file
action [...] is not supported	UnsupportedConfigActionException	Use a valid config action: set, get, unset, reset, list, edit