Validate Troubleshooting
Validate Troubleshooting
Resolve common validation failures before running Custy workflows.
custy validateCategory
Quick Command
custy validateOverview​
Most validation failures occur because one or more project prerequisites have not yet been satisfied.
Fortunately, the reported problem usually includes a helpful hint describing how to resolve it.
Git Repository Not Found​
What you see
Validation stops immediately and reports that the current directory is not a Git repository.
Why it happens
The project has not yet been initialized with Git.
How to resolve it
Initialize the repository.
git init
After initialization, run the validation command again.
Configured Remote Not Found​
What you see
Custy reports that the configured Git remote cannot be found.
Why it happens
The configured remote name does not exist in the repository.
How to resolve it
Verify the configured remote.
git remote -v
If necessary, add the missing remote.
git remote add origin <repository-url>
Alternatively, update the configured remote name in
.config/custy/config.toml.
Version File Missing​
What you see
Validation reports that the configured version file does not exist.
Why it happens
The configured version file has not been created or the configured path is incorrect.
How to resolve it
Review the configured version file path.
If the project has not yet been initialized, run:
custy init
or
custy init --mode config
depending on your project's setup.
Commit Message Template Missing​
What you see
The required commit message template cannot be found.
Why it happens
Template resources have not been generated.
How to resolve it
Generate the required templates.
custy init --mode templates
Then rerun the validation command.
Tag Message Template Missing​
What you see
The configured tag message template is missing.
Why it happens
Template initialization has not been completed.
How to resolve it
Generate the required templates.
custy init --mode templates
or regenerate project resources using
custy init
No Staged Changes​
What you see
Validation reports that no staged files are available.
Why it happens
Project files have not yet been staged.
How to resolve it
Stage the required files.
git add .
or
git add <file>
After staging your changes, rerun validation.
Commit Convention Validation Failed​
What you see
Commitizen configuration, availability, or final message validation fails.
Why it happens
The selected provider is strict but configuration or cz is missing, the
configuration is malformed, or the final message violates project rules.
How to resolve it
Read the structured error label, then install custy[commitizen], repair the
detected configuration, update the message, or select provider = "custy".
Version strategy and message provider are independent. See the
behavior matrix.
Next Diagnostic Step​
If validation continues to fail:
- Confirm that you are working inside the correct project directory.
- Review your
.config/custy/config.tomlconfiguration. - Verify that required project resources exist.
- Run the command again after correcting the reported issue.
Most validation problems are resolved by addressing the first reported error, since Custy uses a fail-fast validation strategy.