Introduction

Git's "not something we can merge" error means the argument you passed to git merge does not resolve to a valid commit reference. Git has not even attempted a merge. It is telling you the target name is unrecognizable. The fix is almost always one of these: correct a typo in the branch name, fetch the remote reference you have not pulled down yet, or use the proper remote-tracking branch name instead of the bare branch name.

This error is not a merge conflict. It fires before Git examines any file content. Once you understand that distinction, debugging becomes straightforward.

Reproduce the Error

Here is the simplest way to trigger this error:

git merge nonexistent-branch
# merge: nonexistent-branch - not something we can merge

Git tried to resolve nonexistent-branch as a commit-ish (a branch, tag, commit hash, or any reference that points to a commit) and failed. The same error occurs with typos, unquoted branch names containing special characters, or remote branches that have not been fetched.

Cause 1: Typo in the Branch Name

The most common cause by far. Branch names are case-sensitive and exact-match only.

1# Wrong
2git merge feature/user-athentication
3
4# Right
5git merge feature/user-authentication

To find the correct name, list your branches:

1# Local branches
2git branch
3
4# Remote-tracking branches
5git branch -r
6
7# All branches (local + remote-tracking)
8git branch -a

If you are unsure about the exact name, use pattern matching:

git branch -a | grep -i auth
# remotes/origin/feature/user-authentication

Cause 2: Remote Branch Not Fetched

You cannot merge a remote branch that Git has not fetched locally. This happens when a teammate creates a new branch and you try to merge it without fetching first.

1# This will fail if you have not fetched
2git merge origin/feature/new-api
3# merge: origin/feature/new-api - not something we can merge
4
5# Fix: fetch first, then merge
6git fetch origin
7git merge origin/feature/new-api

A common variation is trying to merge a bare branch name when you actually mean the remote-tracking ref:

1# This merges your LOCAL main branch
2git merge main
3
4# This merges the remote-tracking branch (latest from remote)
5git merge origin/main

These are different references. If your local main is behind the remote, merging local main will not bring in the latest changes.

Cause 3: The Argument Is Not a Commit-ish

git merge expects something that resolves to a commit. It does not accept file paths, directory names, or arbitrary strings.

1# These all fail
2git merge src/main/java
3git merge README.md
4git merge "my branch"  # if the branch name has no spaces, quotes are fine
5                       # but if no branch named "my branch" exists, this fails

To verify whether a reference resolves to a commit:

1git rev-parse --verify feature-branch
2# If it prints a SHA, the ref is valid
3# If it prints an error, the ref does not exist
4
5git show --oneline --no-patch feature-branch
6# Shows the commit info if the ref is valid

Cause 4: Detached HEAD or Stale State

If you are in a detached HEAD state and trying to merge a branch that was deleted and recreated, the local reference may be stale.

1# Check your current state
2git status
3# HEAD detached at abc1234
4
5# Refresh all remote refs and prune deleted ones
6git fetch --all --prune

After fetching with --prune, deleted remote branches are cleaned up from your local remote-tracking refs, preventing confusion.

Cause 5: Special Characters in Branch Names

Branch names containing characters that the shell interprets specially can cause this error if not properly quoted or escaped.

1# Branches with forward slashes work fine
2git merge feature/user-auth
3
4# But brackets, spaces, or other special chars need quoting
5git merge "bugfix/issue#123"

If you suspect the branch name contains unusual characters, list branches with git branch -a and copy the exact name.

Step-by-Step Debugging Workflow

When you hit this error, follow this sequence:

1# 1. Verify the ref exists
2git rev-parse --verify <branch-name>
3
4# 2. If not found, check if it is a remote branch
5git branch -r | grep <partial-name>
6
7# 3. If it exists remotely but not locally, fetch
8git fetch origin
9
10# 4. Try the merge again with the full ref name
11git merge origin/<branch-name>
12
13# 5. If still failing, check for typos
14git branch -a | grep -i <partial-name>

Merge vs. Other Git Operations

This same "not something we can merge" pattern applies to related commands:

1# Rebase
2git rebase origin/feature-branch
3# If the ref is invalid, you get a similar "invalid upstream" error
4
5# Cherry-pick (expects a commit SHA or ref)
6git cherry-pick abc1234
7
8# Checkout
9git checkout feature-branch
10# "error: pathspec 'feature-branch' did not match any file(s)"

Each command has a slightly different error message, but the root cause is always the same: the reference does not resolve to what the command expects.

Reference Resolution Cheat Sheet

Common Pitfalls

Assuming this error means a merge conflict. It does not. Git never reached the point of comparing file contents. The reference itself is the problem. Merge conflicts are a completely separate error that only appears after Git successfully identifies both sides of the merge.

Forgetting the difference between local and remote-tracking branches. main and origin/main are separate references. If you want the latest remote version, you must fetch first and then reference origin/main.

Not fetching after a teammate creates a new branch. Your local clone only knows about remote branches at the time of your last fetch. New branches created by others are invisible until you run git fetch.

Using git pull when you need git fetch. git pull fetches and merges (or rebases) into the current branch. If you want to merge a different branch, git fetch followed by git merge origin/that-branch is the correct workflow.

Confusing git merge with git checkout. If you want to switch to a branch rather than merge it into your current branch, use git checkout or git switch. Merge combines histories; checkout moves your working tree to a different branch.

Summary

The "not something we can merge" error is a reference resolution failure, not a merge conflict. Git cannot find the commit you asked it to merge. To fix it: verify the branch name with git branch -a, fetch remote refs with git fetch origin, use the correct remote-tracking name like origin/branch-name, and check for typos. Always treat this as a "does the ref exist" problem first. Once Git can resolve the reference, the merge will either succeed cleanly, produce a conflict (a different problem), or fast-forward.