Skip to main content

Commit Troubleshooting

Commit Troubleshooting

Support Guide

Resolve version-file, staging, editor, validation, changelog, and commit-content problems.

Commandcusty commit

Category

Git Operations

Quick Command

custy commit [OPTIONS]
troubleshootingstagingrecovery

Overview​

Stop at the first failed or unexpected stage. The profile can leave generated files, backups, or staged changes even when the final commit is not created.

No Version File Was Found​

Confirm [tool.custy.cli.paths].version_file or pass --version-file with an existing writable file.

The Wrong Files Were Staged​

Stop before pushing. Inspect the working tree and index:

Terminal
bash
git status
git diff --cached

Review auto_stage and stage_mode; use update, manual, or none when appropriate for the project.

The Editor Did Not Open​

Verify the commit-message template path and use an interactive environment when editing is expected. Review tool.custy.editor, VISUAL, and EDITOR. On Windows, the generated defaults prefer VS Code and then Notepad; Custy resolves the actual code.CMD path before launch. In a container, keep -it and use an editor installed inside the image. The output identifies unavailable candidates before a fallback is selected.

Commit Validation Failed​

Read the first validation error, correct repository state or message content, and run dry-run again. Do not use --allow-empty-commit to bypass an unrelated validation problem.

Commitizen Was Not Configured or Installed​

COMMITIZEN_NOT_CONFIGURED means strict Commitizen validation was requested without .cz.toml, .cz.yaml, .cz.yml, .cz.json, or [tool.commitizen]. COMMITIZEN_NOT_AVAILABLE means configuration exists but cz is unavailable. Install custy[commitizen], correct the configuration, or choose provider = "custy". Review the provider behavior matrix.

A Git Hook Rejected the Commit​

PRE_COMMIT_HOOK_FAILED means Custy successfully selected direct pre-commit execution, but a configured check rejected or modified files. Read the captured output, repair and stage the result, then retry. GIT_HOOK_FAILED means native Git still rejected the commit. GIT_HOOK_POLICY_INVALID means safe adaptation was unavailable, such as an unknown incompatible custom hook or missing pre-commit executable. Review the hook behavior matrix; Custy does not silently bypass hooks.

Changelog Generation Failed​

Resolve the changelog error before retrying the whole commit profile. The Changelog troubleshooting guide explains common collection and rendering problems.

A Commit Contains Incorrect Content​

Do not rewrite shared history automatically. Inspect whether the commit has been pushed and follow your team's correction policy. Preserve unrelated changes.