Git: You are in 'detached HEAD' state

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Create branch from current commit
git switch -c new-branch-name
# Or go back to existing branch
git switch main
# If you made commits, cherry-pick them
git cherry-pick <commit-hash>

How to diagnose Git errors

Git errors are frightening mostly because the messages describe internal state rather than what to do. The reassuring fact is that almost nothing is lost: git reflog records every position HEAD has held, so a bad rebase, a hard reset or a deleted branch is nearly always recoverable. Before running any destructive command, note the current commit hash.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Run git status and read it fully. It tells you the current state and usually names the exact command to move forward or abort.
2. Use git reflog to find any commit you think you have lost, then git reset --hard <hash> or git branch recovery <hash> to get it back.
3. For a rejected push, run git fetch then git log --oneline HEAD..@{u} to see exactly what is on the remote that you do not have. Prefer --force-with-lease over --force, which refuses to overwrite work you have not seen.
4. Abort rather than improvise when a merge or rebase goes wrong: git merge --abort, git rebase --abort, git cherry-pick --abort.
5. For repository corruption, run git fsck --full. If objects are missing, re-cloning and cherry-picking your local work is usually faster and safer than repairing in place.

Tools worth reaching for

• git status
• git reflog
• git fsck --full
• git log --graph --oneline --all
• git diff --check

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 git-scm.com

Related Git errors

• git cherry-pick: conflictThe commit being cherry-picked modifies lines that diverged on the target branch, so Git…
• Git LFS: missing objectsGit LFS pointer files exist but the actual large file content was not downloaded. The LFS…
• git: cannot lock refAnother Git process is holding a ref lock or a stale .lock file remains from a crashed Git…
• Git: CONFLICT during rebaseA merge conflict occurred while replaying commits during a rebase. The same lines were…
• Git: Could not apply stashApplying a stash caused conflicts because the working tree has diverged from when the stash…
• git: detected dubious ownership in repositoryGit refuses to operate on a repository owned by a different user than the one running git…
• git: error: pathspec 'x' did not match any file(s) known to gitGit could not resolve the argument as a file, branch or commit. With checkout it usually…
• Git: failed to push some refs to ... (non-fast-forward)Remote branch has commits that you don't have locally. Someone else pushed changes.

See all 20 Git errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.