How to fix warning: refname 'feature' is ambiguous in Git

GitINTERMEDIATELOWUpdated May 28, 2026· 326 views

This Git warning occurs when a short reference name (like 'feature') matches multiple refs, such as a branch and a tag with the same name. Use the full refname or remove the duplicate ref.

Quick fix

Fixes warning: refname 'feature' is ambiguous

# Show all refs matching the name
git show-ref feature

# Example output showing the conflict:
# a1b2c3d refs/heads/feature
# e4f5a6b refs/tags/feature
  1. Identify all conflicting references
  2. Use the full refname to specify the exact reference
  3. Delete the conflicting tag
  4. Delete the conflicting branch
git — error
# Show all refs matching the name
git show-ref feature
# Example output showing the conflict:
# a1b2c3d refs/heads/feature
# e4f5a6b refs/tags/feature
warning: refname 'feature' is ambiguous

What this error means

This warning appears when Git finds multiple references matching the same name in your repository. Git stores references in several namespaces: `refs/heads/` for branches, `refs/tags/` for tags, `refs/remotes/` for remote-tracking branches, and others. When you use a short reference name like "feature", Git searches through these namespaces in a specific order. If it finds "feature" in more than one location (for example, both `refs/heads/feature` and `refs/tags/feature`), it issues this ambiguous refname warning. While Git will typically proceed using its priority rules (tags are checked before branches in the lookup order, so a tag can win over a branch of the same name), the warning indicates that you may not be working with the reference you intended. This can lead to unexpected behavior, especially during merges, checkouts, or when setting upstream branches.

Typical symptoms

  • Git commands print a 'warning: refname 'X' is ambiguous' message
  • Checkout or merge operations may resolve to an unexpected branch or tag
  • git log or git show displays the warning before its output
  • Setting an upstream branch shows the ambiguity warning
  • git diff comparisons may reference the wrong commit
  • CI/CD pipelines fail or produce unexpected results because the wrong ref is used
  • Push operations target the wrong reference

Common causes

  1. A tag and a branch have the same name (most common cause)
  2. A local branch was accidentally created with an 'origin/' prefix (e.g. 'origin/feature') instead of checking out the remote-tracking branch
  3. A tag was created with the same name as an existing branch during a release
  4. An imported or migrated repository has naming conflicts from different naming conventions
  5. A stray or erroneous ref file exists in the .git/refs/ directory
  6. A typo created a ref in the wrong namespace

How to fix "warning: refname 'feature' is ambiguous"

1Identify all conflicting references

First, find all references that match the ambiguous name:

bash
# Show all refs matching the name
git show-ref feature

# Example output showing the conflict:
# a1b2c3d refs/heads/feature
# e4f5a6b refs/tags/feature

You can also search more broadly:

bash
# Find all references containing the name
git show-ref | grep feature

# List all branches and tags
git branch -a
git tag -l

This reveals whether the ambiguity is between a branch and a tag, or involves other reference types.

2Use the full refname to specify the exact reference

To avoid ambiguity in your commands, use the full reference path. This is non-destructive and is the safest first move:

bash
# Checkout the branch (not the tag)
git checkout refs/heads/feature

# Checkout the tag (not the branch)
git checkout refs/tags/feature

# Merge using an explicit branch reference
git merge refs/heads/feature

# Compare using explicit references
git diff refs/heads/feature refs/tags/feature

# Set upstream with an explicit remote-tracking reference
git branch --set-upstream-to=refs/remotes/origin/main main

You can also use shorter but still unambiguous forms:

bash
# Use the heads/ prefix for branches
git checkout heads/feature

# Use the tags/ prefix for tags
git checkout tags/feature
3Delete the conflicting tag

If the tag is no longer needed or was created by mistake, delete it. Before deleting, confirm what it points to with git show refs/tags/feature so you do not lose a release marker you still need.

bash
# Delete the local tag
git tag -d feature

# If the tag also exists on the remote, delete it there using the refspec form
git push origin :refs/tags/feature

# Equivalent explicit form
git push origin --delete refs/tags/feature

Note: git push origin --delete tag feature is not valid syntax — use one of the two forms shown above.

After deleting, verify the ambiguity is resolved:

bash
git show-ref feature
# Should now show only one reference
4Delete the conflicting branch

If the branch is the duplicate that should be removed, first confirm what each ref points to so you delete the right one:

bash
# Compare what each ref points to before deleting
git log -1 refs/heads/feature
git log -1 refs/tags/feature

Then delete the branch:

bash
# Delete the local branch (safe: refuses if unmerged)
git branch -d feature

# If you have verified the work is preserved elsewhere, force-delete
# WARNING: -D discards unmerged commits on this branch. Confirm first.
git branch -D feature

# If it is a remote branch
git push origin --delete feature
5Clean up an erroneous ref in the .git directory

Occasionally a typo or a failed operation leaves a stray ref. Inspect them first:

bash
# Inspect refs (works for both loose and packed refs)
git for-each-ref | grep feature

# Loose ref files live under .git/refs/
ls -la .git/refs/heads/
ls -la .git/refs/tags/

If you find an erroneous ref, remove it with Git rather than deleting files by hand. git update-ref -d is safe, atomic, and also handles refs that are stored in packed-refs (which manual rm would miss):

bash
# Delete a reference safely
git update-ref -d refs/heads/origin/feature

Avoid rm .git/refs/... directly: it leaves packed refs and reflogs inconsistent and will not work for packed refs.

6Rename a conflicting branch to avoid future issues

If you need to keep both references, rename the branch so the names are unique:

bash
# Rename the local branch
git branch -m feature feature-branch

# Update the remote: push the new name and set upstream
git push origin -u feature-branch

# Delete the old remote branch once the new one exists
git push origin --delete feature

Recommended naming conventions to avoid collisions:

| Type | Convention | Example |
|------|------------|---------|
| Feature branch | feature/name | feature/user-auth |
| Release branch | release/version | release/1.2.0 |
| Release tag | vX.Y.Z | v1.2.0 |
| Hotfix branch | hotfix/name | hotfix/login-fix |

Using prefixes like feature/ and release/ for branches and v for tags naturally prevents name collisions.

7Clean up a local branch named like a remote

A common mistake is creating a local branch named like origin/feature instead of checking out the remote-tracking branch:

bash
# This creates a local branch literally named 'origin/feature' (wrong)
git branch origin/feature

# This creates a local 'feature' branch tracking the remote (correct)
git checkout feature   # or: git switch feature

To fix the mistake, delete the incorrectly named local branch:

bash
# -D is needed because Git treats this as an unmerged branch.
# Confirm with 'git log -1 origin/feature' first; the real remote ref
# is refs/remotes/origin/feature and is unaffected.
git branch -D origin/feature

# Now the short name resolves cleanly
git switch feature

Verify the fix:

bash
git show-ref | grep feature
# Should show only the expected refs

Advanced notes

### Git reference resolution order

When you provide a short refname, Git resolves it against these patterns in order (see gitrevisions):

1. $GIT_DIR/<refname> (e.g. HEAD, FETCH_HEAD, MERGE_HEAD, CHERRY_PICK_HEAD)
2. refs/<refname>
3. refs/tags/<refname>
4. refs/heads/<refname>
5. refs/remotes/<refname>
6. refs/remotes/<refname>/HEAD

The first match wins. Note that tags (rule 3) are checked before branches (rule 4), so when a tag and a branch share a name, the tag is what a bare short name resolves to — and Git warns because that is rarely what you intended.

### Checking for ambiguous refs repository-wide

bash
# List names that exist as both a branch and a tag
git for-each-ref --format='%(refname:short)' refs/heads refs/tags | \
  sort | uniq -d

Any output indicates names that are ambiguous.

### Preventing ambiguous refs in team workflows

Establish naming conventions:
- Use a v prefix for version tags: v1.0.0, v2.1.3
- Use directory-style branch names: feature/X, bugfix/Y
- Never name a tag the same as a branch

You can also add a server-side pre-receive hook that rejects a push which would create a name existing as both a branch and a tag:

bash
#!/bin/bash
while read oldrev newrev refname; do
  shortname=${refname##*/}
  if git show-ref --verify --quiet "refs/heads/$shortname" && \
     git show-ref --verify --quiet "refs/tags/$shortname"; then
    echo "Error: '$shortname' would exist as both a branch and a tag (ambiguous ref)"
    exit 1
  fi
done

### The core.warnAmbiguousRefs setting

core.warnAmbiguousRefs is true by default. Setting it to false only suppresses the warning — it does not change which ref Git picks, and the underlying ambiguity (and its risk of resolving to the wrong object) remains. Prefer resolving the ambiguity over hiding the warning.

### Remote-tracking branch ambiguity

A related case involves a local branch accidentally created with a remote-style name:

text
refs/heads/origin/feature     # local branch (mistake)
refs/remotes/origin/feature   # remote-tracking branch (correct)

This usually happens when someone runs git branch origin/feature instead of git switch feature. Delete the stray local branch with git branch -D origin/feature (see step 7).

Frequently asked questions

What does "warning: refname 'feature' is ambiguous" mean?
This warning appears when Git finds multiple references matching the same name in your repository. Git stores references in several namespaces: refs/heads/ for branches, refs/tags/ for tags, refs/remotes/ for remote-tracking branches, and others. When you use a short reference name like "feature", Git searches through these namespaces in a specific order.
How do I fix "warning: refname 'feature' is ambiguous"?
This Git warning occurs when a short reference name (like 'feature') matches multiple refs, such as a branch and a tag with the same name. Use the full refname or remove the duplicate ref.
What causes "warning: refname 'feature' is ambiguous"?
A tag and a branch have the same name (most common cause) A local branch was accidentally created with an 'origin/' prefix (e.g. 'origin/feature') instead of checking out the remote-tracking branch A tag was created with the same name as an existing branch during a release
Is the "warning: refname 'feature' is ambiguous" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading