Errors and Exit Status

🚀Errors and Exit Status

Current Runtime Behavior

Interpret parser feedback, structured validation labels, pipeline failures, subprocess errors, and current process status.

Commandcusty COMMAND

📦Category

Reference

🚀Quick Command

status + message + optional diagnostic label

---

exit 0exit 1usage 2ValidationError

---

✅

Success

0

Explicit/Application Failure

1

⚠️

Typer/Click Usage Error

2

🛡️

Rollback

None

Process Status Reference

ℹ️Current Status Behavior

0 - successful completion	A command or pipeline reached its normal completion boundary without an uncaught failure.
1 - explicit or application failure	Used by Custy validators, progress wrappers, root no-command behavior, and most uncaught application exceptions.
2 - command-line usage error	Typer/Click uses this for unknown commands, unknown options, missing required values, and invalid parameter input.
Subprocess status	Git, Commitizen, or editor commands have their own return codes. Custy may wrap, normalize, log, or re-raise those failures rather than expose the same numeric value.

⚠️Root help and version currently exit with 1

The current root callbacks explicitly use status 1 after displaying custy --help, displaying custy --version, or showing root help because no command was selected. Do not assume these two informational root options return zero in automation until the implementation changes.

---

Error Families

ℹ️How Failures Surface

CLI parsing	Typer explains the invalid command, option, enum, tag, or missing argument before command execution begins.
ConfigurationError	Invalid TOML, an unreadable configuration file, a required missing property, or an invalid project-source directory.
ValidationError	A workflow precondition with a message, optional hint, diagnostic label, default exit_code of 1, and optional context.
GitOperationError	A repository operation failed at the high-level Git service boundary.
BranchCleanupError	Branch cleanup could not evaluate or delete an eligible branch; protected and deletion failures have dedicated subclasses.
Pipeline failure	The active progress UI identifies the failing step, stops execution, and re-raises the original exception.
External tool failure	Git, Commitizen, or a configured editor could not be launched or returned an unsuccessful result.
Unexpected exception	Typer's pretty-exception behavior or Python traceback reports an unhandled implementation failure.

---

Structured Validation Labels

The active workflow and commit validator attach labels such as:

• Repository and remotes: NOT_GIT_REPO, REMOTE_NOT_FOUND, MAIN_REMOTE_MISSING.
• Files and editor: VERSION_FILE_NOT_FOUND, COMMIT_MSG_PATH_MISSING, COMMIT_MSG_FILE_NOT_FOUND, TAG_MSG_PATH_MISSING, TAG_MSG_FILE_NOT_FOUND, EDITOR_LAUNCH_FAILED, EDITOR_PROCESS_FAILED.
• Commit content: EMPTY_COMMIT_MSG, INVALID_COMMIT_FORMAT, INVALID_COMMIT_TYPE, COMMIT_MESSAGE_MISSING, COMMITIZEN_NOT_CONFIGURED, COMMITIZEN_NOT_AVAILABLE, COMMITIZEN_CONFIGURATION_INVALID, COMMITIZEN_CHECK_FAILED, COMMITIZEN_FAILED.
• Staging: EMPTY_STAGING_ABORTED, NO_STAGED_FILES, NO_STAGED_CHANGES, INVALID_STAGE_MODE, AUTO_STAGE_FAILED, STAGING_FAILED.
• Version and tag: INVALID_VERSION_INPUT, TAG_MISSING, TAG_CREATION_FAILED.
• Publication and finalization: GIT_COMMIT_FAILED, GIT_HOOK_FAILED, COMMIT_FAILED, PUSH_FAILED, PUSH_TAG_FAILED, POST_WORKFLOW_FAILED.

ℹ️Labels are diagnostic, not stable numeric codes

These strings help people and logs identify the failing condition. Custy does not currently publish a centralized, versioned error-code registry, and one active commit-validator label even contains spaces. Automation should use the documented process status and observable result, not parse these labels as a permanent API.

---

Pipeline Failure Boundary

Pipelines are sequential and non-transactional. When a step fails:

1. The active pipeline reports the step name.
2. Execution stops before later steps run.
3. The exception is re-raised.
4. Earlier file, Git, backup, commit, tag, or remote effects are not automatically reversed.

Inspect git status, recent commits, tags, remotes, generated files, backups, and logs/custy.log before retrying.

---

Automation Pattern

PowerShell

powershell

custy --no-banner validate
if ($LASTEXITCODE -ne 0) {
  throw "Custy validation failed with exit code $LASTEXITCODE"
}

Use --no-banner for compact output and a UTF-8-capable capture stream. Do not use root --help or --version as zero-status health checks with the current implementation.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Troubleshooting Workflows

Follow a safe diagnosis and recovery sequence.

Environment

Check runtime, encoding, editor, Git, and working-directory assumptions.

Global Options

Use debug, log-level, no-banner, and dry-run behavior correctly.

Safety and Side Effects

Understand non-transactional changes and recovery responsibility.