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

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.

hatchling

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

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

pyproject.toml

[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.

Terminal

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.