Git you-need-to-resolve-your-current-index-first A branch switch or similar operation stopped because the index still holds unmerged entries.

dev@local: ~/project — git

dev@local~/project$git checkout <branch>

error: you need to resolve your current index first

Diagnostics Translation

A branch switch or similar operation stopped because the index still holds unmerged entries.

waiting for resolution...

LowVersion Control System

Reviewed for reference consistency: August 11, 2026

Code is Safe

SECURE

Git has paused the operation to protect your code. No data has been lost or corrupted.

What To Know

The index is holding multi-stage conflict entries, and Git will not build another branch's checkout on top of an unresolved set of file versions.

Where Did It Fail?

Working Tree

Your local files

add

Staging Index

Prepared changes

commit

Local Repo

Commit history

push/fetch

Remote Server

GitHub/GitLab

The error occurred during a network exchange. Your local files are untouched, but Git cannot reach the remote server.

Commands That Trigger This

$git checkout <branch>

Running in the middle of a conflicted merge

$git status

Attempting a branch switch while still lists paths under Unmerged paths

Starting a second topic-branch checkout right after a conflicted stash pop

Technical Background

The index is the staging ledger Git reads when assembling a checkout. Unmerged entries store up to three versions of one path — the common ancestor, your side, and the incoming side — and no single answer exists for what that file contains until a human picks or writes one.

Checking out a different branch would need to replace or merge those stages against a new commit, which multiplies the ambiguity instead of reducing it. The refusal keeps the conflict isolated inside the operation that created it.

Resolution clears the state: after the file content is settled and staged, the multi-stage entries collapse to one, and branch switching becomes possible again.

Underlying Causes

A merge stopped on conflicts and the affected files were never staged after resolution

Conflict markers were edited in the files but `git add` was not run

A rebase or cherry-pick left unmerged index stages behind

A stash application produced conflicts that were left pending

Frequently Asked Questions

The two messages travel together: unmerged-paths names the files, this refusal explains why the next operation cannot run while they stay unresolved.

Checkout offers no safe discard for a conflicted index; the resolution has to be recorded, or the originating merge or rebase aborted, before the switch succeeds.

Related Git States

merge-conflictMedium

Git paused the merge because it cannot automatically resolve overlapping changes.

stash-pop-conflictMedium

Reapplying a stash hit conflicts, and the stash entry was deliberately kept.

unmerged-pathsLow

You have unresolved file conflicts preventing Git from completing the current operation.

rebase-in-progressLow

You tried to run a Git command while a previous rebase operation is still paused.