Skip to main content

Git Troubleshooting

Git Troubleshooting

Repository Recovery

Verify local and remote repository state before retrying commit, tag, push, cleanup, or release behavior.

Commandgit status

Category

Troubleshooting

Quick Command

inspect local state -> inspect destinations -> correct -> verify
stagingtagsremotesbranches
Repository Service
GitService
Primary Evidence
Git state and remote response
Remote Verification
Per destination
Force Recovery
Policy approval required

Scope of This Page​

Use this page when a problem crosses command boundaries or when you need to inspect shared repository, reference, branch, or remote state. For an error that clearly belongs to one invocation, use the linked Commit, Tag, Push, or Branch Cleanup guide for focused recovery steps.

Inspect Before Retrying​

Local and remote evidence
bash
git status --short --branch
git diff
git diff --staged
git log -3 --decorate --oneline
git tag --points-at HEAD
git remote -v
git branch --all

Repository and Staging

Information

NOT_GIT_REPORun Custy from the intended repository root and confirm git status works there.
NO_STAGED_FILES or NO_STAGED_CHANGESInspect the index. Stage only reviewed files or adjust auto_stage and stage_mode deliberately.
INVALID_STAGE_MODEUse the supported all, update, manual, or none behavior for the selected command.
AUTO_STAGE_FAILED or STAGING_FAILEDRead the underlying Git response, file permissions, ignore rules, and repository state before repeating.
Unexpected staged contentStop before commit or push; compare git diff and git diff --staged, then reconcile according to project policy.

Commits and Message Validation

  • Confirm the configured commit-message path exists and contains reviewed content.
  • Read the first commit-format or Commitizen validation message rather than bypassing the entire validation profile.
  • Verify whether the commit already exists before retrying a partial pipeline.
  • Do not rewrite a pushed commit automatically; follow the repository's shared history policy.

See Commit Troubleshooting for the focused message, editor, staging, changelog, and content checks.

Tags

Inspect a tag locally and remotely
bash
git show --decorate <tag>
git ls-remote --tags origin <tag>

If a tag already exists, compare its target and annotation before choosing a new approved version. Never move or replace a published tag casually; release assets and CI/CD may already depend on it.

Remotes, Authentication, and Push

  • REMOTE_NOT_FOUND or MAIN_REMOTE_MISSING: compare git remote -v with tool.custy.git and the Push command's resolved destinations.
  • Authentication failure: test Git directly and repair the credential manager, SSH agent, provider permission, or CI secret without placing credentials in Custy configuration.
  • Rejected update: read the remote response for non-fast-forward history, required review, branch protection, or missing permission.
  • Partial multi-remote success: verify every destination independently and recover only failed destinations.
  • Do not force-push unless the repository's explicit policy permits it.

Branch Cleanup

No deletion can be correct behavior when a branch is protected, outside the configured prefixes, too new, not in the selected merge state, or the command is in dry-run mode. Review candidates before changing filters, and never weaken protected-branch safeguards simply to make cleanup remove more branches.

Continue

Related Commands

Commands commonly used together with this command.