Skip to content

git tag: invalid tag name format

Quick summary

You tried to create a tag with a name containing spaces, colons, or other forbidden characters — git rejects it as an invalid ref name.

Why this happens

  • The tag name contains spaces, tildes, carets, or colons which are not allowed in git reference names

  • The tag name starts with a dot, dash, or slash which makes it an invalid ref namespace prefix

  • The tag name contains double dots (..) or ends with .lock, which git reserves for internal use

Minimal example

✗ Broken code
git tag 'v1.0: beta'  # error: invalid tag name: 'v1.0: beta'
✓ Fixed code
git tag 'v1.0-beta'  # valid tag name with hyphen instead of colon-space

Colons and spaces are forbidden in git ref names — replacing them with a hyphen produces a valid tag name that git accepts.

How to diagnose

  • Check the tag name for forbidden characters: space, ~, ^, :, ?, *, [, \, and control characters

  • Run git tag to list existing tags and compare naming conventions with your intended tag name

  • Use git check-ref-format <tag-name> to validate the name before creating the tag

How to fix

  • Replace forbidden characters with hyphens or underscores, e.g., 'v1.0-rc' instead of 'v1.0 rc'

  • Remove leading dots or dashes and ensure the name does not contain double dots or end with .lock

  • Use git check-ref-format --branch <name> to validate and normalize the tag name before creating it

How to prevent

  • Always validate tag names with git check-ref-format before creating tags in scripts or automation

  • Follow a consistent tagging convention like vMAJOR.MINOR.PATCH that avoids all forbidden characters

Related Resources

Related Glossary

Related Lessons

  • git tag

    Learn about tagging releases.

← Back to language