Skip to main content

Troubleshooting Workflows

Troubleshooting Workflows

Recovery Guide

Inspect partial state, identify the failed boundary, and choose the smallest safe recovery action.

Commandcusty --debug

Category

User Guide

Quick Command

observe -> inspect state -> correct cause -> recover narrowly -> verify
partial pipelinefilescommittagremote
Failure Behavior
Stop at first raised error
Automatic Rollback
No
Recovery Scope
Last completed boundary
Primary Evidence
Output, logs, Git state

First Principle​

A failed Custy pipeline is not necessarily an untouched pipeline. Earlier steps may have generated or edited files, pruned backups, staged changes, created a commit or tag, or updated one or more remotes.

Recovery Method

Diagnose Before Changing State

1
Capture the failure
Save the failed step name, error code or message, hint, and reported destinations.
completed
2
Inspect current state
Check files, index, latest commit, tags, branches, backups, and remotes.
completed
3
Find the last completed boundary
Determine which durable effects already exist and which later stages never ran.
completed
4
Correct the original cause
Fix the first validation, configuration, content, Git, authentication, or remote error.
current
5
Recover narrowly and verify
Use the smallest direct command or manual action that completes or reconciles the intended state.
pending

Evidence Checklist

Inspect local 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 the first errorRequired

    Later messages can be consequences; begin with the step that raised the failure.

  • Inspect generated filesRequired

    Check version files, editable artifacts, CHANGELOG.md, and message files.

  • Inspect backupsRequired

    Confirm whether new copies were created or older copies were pruned.

  • Inspect Git objectsRequired

    Determine whether staging, commit, tag, or branch deletion already occurred.

  • Inspect every destinationRequired

    For multi-remote work, verify each remote independently.

Choose Recovery by Last Completed Effect

Common Boundaries

Validation Only

Fix the reported prerequisite. Later mutation steps did not run.

Files Changed

Review and reconcile generated files and the index before running any command again.

Commit Exists

Do not recreate the same commit blindly. Determine whether tag or push is the remaining intended action.

Tag Exists

Verify the tag target and message before deciding whether only push remains.

Some Remotes Succeeded

Repair authentication or policy for failed destinations and avoid duplicating successful publication.

Finalization Failed

Release may already be published. Inspect branch transitions separately rather than rerunning Full.

Improve Diagnostic Output

Global options belong before the command group.

Diagnostic invocations
bash
custy --debug run release
custy --log-level DEBUG run dev
custy --debug cleanup brancheses --prefix feature/

Use debug output to understand resolution and execution, but do not include secrets, tokens, or sensitive remote credentials when sharing logs.

Escalate When State Is Unclear

Stop and ask a teammate or repository administrator before deleting commits or tags, force-pushing, changing shared branches, restoring remote branches, or rewriting published release history. Preserve logs and current state while the recovery decision is reviewed.

Continue

Related Commands

Commands commonly used together with this command.