Skip to main content

Workflow Troubleshooting

Workflow Troubleshooting

Pipeline Recovery

Find the last completed step and recover from current state instead of assuming the profile rolled back.

Commandcusty --debug run PROFILE

Category

Troubleshooting

Quick Command

profile -> expanded steps -> first failure -> narrow recovery
profilesorderingpartial stateexperimental workflow
Public Run Names
6
Execution
Sequential
Failure Policy
Stop and re-raise
Rollback
None

Scope of This Page​

Use this page when a Run profile or experimental workflow crosses several steps and may have left partial state. Use the Run or Workflow Branch command guide when the failing invocation and symptom are already clear.

Find the Last Completed Boundary​

Partial Pipeline Recovery

1
Read the failed step
Capture its name, message, hint, diagnostic label, and reported paths or remotes.
completed
2
List earlier durable effects
Check files, backups, index, commits, tags, branches, and all destinations.
completed
3
Correct the original cause
Fix the first validation, configuration, content, Git, authentication, or implementation problem.
current
4
Choose narrow recovery
Use a direct command or manual action only for the remaining intended result.
pending
5
Verify final state
Confirm local files, Git references, logs, and every remote before declaring recovery complete.
pending

Common Symptoms

Information

Profile name rejectedUse commit, tag, push, dev, release, or full. Other resolver profiles are not additional public Run names.
Combined profiles run in another orderMultiple profiles are expanded, deduplicated, and stably sorted by global STEP_ORDER priority. This is intentional.
Duplicate or mixed input rejectedRemove duplicate values and follow the typed validator's supported manual or profile composition rules.
Validation stops executionCorrect the first prerequisite. Later mutation steps intentionally do not run after validation raises.
Files changed before failureInspect generated artifacts, messages, changelog, backups, and the Git index before retrying.
A Run option has no effectSome accepted fields are not mapped into WorkflowEngine because model and builder names differ. Confirm current option status before relying on it.
Push failed after commit or tagVerify whether local history is already complete and recover only publication rather than recreating commit or tag state.
Full finalization failedThe release may already be published; inspect branch transitions separately instead of rerunning Full.

Inspect Partial State

Evidence after a failed profile
bash
git status --short --branch
git diff
git diff --staged
git log -3 --decorate --stat
git tag --points-at HEAD
git remote -v

Before You Begin

  • Generated filesRequired

    Inspect version files, editable artifacts, CHANGELOG.md, and message templates.

  • Backup retentionRequired

    Confirm whether backups were created and whether cleanup already pruned older files.

  • Commit and tagRequired

    Determine whether either object already exists before invoking a direct command.

  • Every remoteRequired

    Check each configured destination; one successful push does not prove all succeeded.

  • Original errorRequired

    Fix the first raised condition instead of bypassing validation or forcing a later effect.

Experimental Workflow Command

Other current interface limitations include underscore-style option spellings, narrow explicit tag validation, incomplete enforcement behavior, and backup synchronization that must be verified rather than assumed. Keep this command in a disposable repository until the blocker and later behavior are validated.

Recovery Choice

  • If only validation ran, correct the prerequisite and preview again.
  • If files changed but no commit exists, review and reconcile files and the index before choosing Commit or another direct operation.
  • If a commit exists, determine whether Tag or Push is the only remaining goal.
  • If a tag exists, verify its target and message before publishing.
  • If some remotes succeeded, correct only failed destinations.
  • If finalization failed, treat release publication and branch transition as separate recovery problems.

Continue

Related Commands

Commands commonly used together with this command.