hatchling "Field `project.name` is required" in CI

By Kaveh Alemi·Latchkey

hatchling validates [project] against core metadata rules. A required field such as name (or another field your config marks required) being absent or empty stops the build before any files are collected.

What this error means

The hatchling build fails with a message that a required field is missing or empty, such as the project name, naming the offending key.

Field `project.name` is required
# hatchling refuses to build without core metadata

Common causes

A core metadata key is absent

name is mandatory. Omitting it (or leaving it blank) makes the distribution metadata invalid.

The [project] table is incomplete after a migration

Moving from setup.cfg to pyproject.toml can drop fields; hatchling enforces them strictly where older setuptools was lenient.

How to fix it

Fill in the required project fields

1. Add the missing key (for example name) under [project].
2. Confirm name, version (static or dynamic), and other required fields are present.
3. Re-run the build.

[project]
name = "mypkg"
version = "0.1.0"
description = "Example package"

Validate metadata locally before pushing

Build once locally so hatchling surfaces any missing field before CI.

python -m build --wheel
twine check dist/*

How to prevent it

• Keep all required [project] fields populated.
• Run twine check on built artifacts in CI.
• Audit metadata after migrating from setup.cfg.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation