How to fix fatal: tag 'v1.0.0' already exists in Git

First, verify whether the tag exists in your local repository:

git tag -l "v1.0.0"

If this returns the tag name, it exists locally. You can see all tags with:

git tag

To see what commit a tag points to:

git rev-parse v1.0.0

If you want to recreate the tag, first delete the existing local tag:

git tag -d v1.0.0

You should see output like:

Deleted tag 'v1.0.0' (was abc1234)

Now you can create the tag again:

git tag v1.0.0
# Or with a message (annotated tag):
git tag -a v1.0.0 -m "Release version 1.0.0"

If you want to move an existing tag to a different commit without deleting it first, use the -f (force) flag:

git tag -f v1.0.0

This moves the tag to the current HEAD. To move it to a specific commit:

git tag -f v1.0.0 <commit-hash>

For annotated tags, combine -f with -a:

git tag -fa v1.0.0 -m "Updated release 1.0.0"

If the tag also exists on the remote, you need to handle it there too.

Delete the remote tag first:

git push --delete origin v1.0.0
# Or using the colon syntax:
git push origin :refs/tags/v1.0.0

Then push your new tag:

git push origin v1.0.0

Or force-push the tag directly:

git push origin v1.0.0 --force

Warning: Force-pushing tags can cause issues for others who have fetched the old tag. Use with caution in shared repositories.

If your local tags are out of sync with the remote, you can fetch and update them:

Fetch all tags from remote:

git fetch --tags

Force-fetch tags (overwrites local with remote):

git fetch --tags --force

Delete all local tags and re-fetch from remote:

git tag -l | xargs git tag -d
git fetch --tags

This is useful when remote is the source of truth and you want to reset your local tags.

If you're using npm version and it fails because the tag exists:

Delete the conflicting tag first:

git tag -d v1.0.0

Then run npm version again:

npm version patch  # or minor, major, etc.

To prevent npm from creating tags automatically:

npm version patch --no-git-tag-version

This only updates package.json without creating a git tag.

If you have many outdated local tags that don't exist on remote, prune them:

List tags that exist locally but not on remote:

git fetch --prune origin "+refs/tags/*:refs/tags/*"

Or manually compare local vs remote tags:

# List local tags
git tag

# List remote tags
git ls-remote --tags origin

Delete specific local tags that shouldn't exist:

git tag -d old-tag-1 old-tag-2 old-tag-3