Skip to main content

Troubleshooting

Troubleshooting

Central Support Guide

Find the first failing boundary, preserve evidence, correct the cause, and recover without duplicating successful effects.

Commandcusty --debug COMMAND

Category

Troubleshooting

Quick Command

observe -> inspect -> isolate -> correct -> verify
diagnosispartial statesafe recovery
First Evidence
First error or failed step
Automatic Rollback
No
Primary State
Files and Git
Detailed Log
logs/custy.log

How These Guides Are Organized​

The central pages in this section diagnose behavior shared by several commands: Git state, configuration resolution, version formats, changelog stages, and partial pipelines. Once you know which invocation failed, switch to that command's troubleshooting page for the exact symptoms and recovery steps.

Start with the First Failure​

Later messages can be consequences of an earlier problem. Record the first failed step, error message, optional diagnostic label, hint, paths, and remote names before changing anything.

Diagnosis Method

Safe Troubleshooting Sequence

1
Capture the first failure
Save the failed step, exact message, hint, diagnostic label, path, and destination.
completed
2
Inspect current state
Review the working tree, index, latest commit, tags, branches, backups, changelog, and every remote.
completed
3
Choose the failure family
Separate environment, configuration, Git, version, changelog, or orchestration behavior.
current
4
Correct the smallest cause
Fix the first invalid input or state without rewriting unrelated or published work.
pending
5
Preview and verify
Use the narrowest applicable dry-run or direct command, then inspect state again.
pending

Choose by Symptom

Features

Repository, Remotes, or Branches

Use Git Troubleshooting for repository detection, staging, commits, tags, authentication, pushes, and cleanup.

TOML, Paths, or Templates

Use Configuration Troubleshooting for working-directory, precedence, cache, initialization, and file resolution.

Versions or Tags

Use Versioning Troubleshooting for strategy, format, file synchronization, Commitizen, and explicit tags.

CHANGELOG.md

Use Changelog Troubleshooting for missing or duplicate entries, grouping, range, links, templates, and output.

Run Profiles or Partial Pipelines

Use Workflow Troubleshooting for profile names, merged ordering, failed steps, ignored adapters, and experimental behavior.

Evidence Checklist

Inspect local repository state
bash
git status --short --branch
git diff
git diff --staged
git log -3 --decorate --stat
git tag --points-at HEAD
git branch --all
git remote -v

Before You Begin

  • Read output from the beginningRequired

    Begin with the first error, not the final summary or traceback consequence.

  • Open the detailed logRequired

    Use logs/custy.log and increase the root log level when more context is needed.

  • Inspect generated filesRequired

    Check the version file, editable messages, CHANGELOG.md, and unexpected diffs.

  • Inspect durable Git effectsRequired

    Determine whether staging, commit, tag, branch deletion, or any remote push succeeded.

  • Protect unrelated workRequired

    Do not discard, overwrite, reset, or clean files merely to make Custy retry.

  • Redact shared diagnosticsRequired

    Remove credentials, tokens, private URLs, and sensitive commit content before sharing output.

Increase Diagnostic Detail

Global options belong before the selected command.

Diagnostic examples
bash
custy --debug validate
custy --log-level DEBUG changelog generate
custy --debug run release
custy --no-banner --log-level DEBUG push

Debug output explains more resolution and step behavior, but it does not make an unsafe operation reversible.

Escalate Before Destructive Recovery

Ask a repository owner or teammate before deleting commits or tags, force-pushing, rewriting shared history, restoring remote branches, changing protected-branch policy, or replacing customized configuration and templates. Preserve current state and logs while the decision is reviewed.

Continue

Related Commands

Commands commonly used together with this command.