Hatchling Build Fails - Unknown Field or Missing Version in CI

Hatchling validates pyproject.toml strictly. A misnamed table, an unknown field, or a version left dynamic without configuring hatch-vcs makes the build abort before producing a wheel.

What this error means

A python -m build (or pip install .) of a hatchling project fails with Unknown field under [tool.hatch...], or Metadata field 'version' is not set when version is dynamic but no source is configured.

ValueError: Metadata field `version` is not set; if it is intended to be dynamic,
add it to `project.dynamic` and configure a version source under
[tool.hatch.version]

Common causes

Dynamic version with no configured source

Declaring dynamic = ["version"] requires a [tool.hatch.version] source (a file path or the hatch-vcs plugin). Without it, hatchling has nothing to resolve.

Unknown or misplaced config field

Hatchling rejects unrecognized keys under its tables (a typo in [tool.hatch.build.targets.wheel], or a field that belongs under [project]).

How to fix it

Configure the version source

Point hatchling at a file (or hatch-vcs) that supplies the version.

[project]
name = "myapp"
dynamic = ["version"]

[tool.hatch.version]
path = "src/myapp/__about__.py"

Use hatch-vcs for git-tag versioning

For tag-derived versions, add the plugin to build requires and set the source.

[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "vcs"

How to prevent it

• Configure a [tool.hatch.version] source whenever version is dynamic.
• Validate pyproject.toml against hatchling docs; avoid unknown keys.
• Build with python -m build locally before pushing metadata changes.

Related guides