python-poetry/poetry · error · RuntimeError

The lock file does not have a metadata entry. Regenerate the

Error message

The lock file does not have a metadata entry.
Regenerate the lock file with the `poetry lock` command.

What it means

Raised by Locker._get_lock_data() when the parsed lockfile dict has no top-level 'metadata' key. The metadata section is mandatory in every Poetry lockfile (it records lock-version and content-hash); its absence means the file is not a real Poetry lockfile or is from a format too old to use. Poetry refuses to guess and asks you to regenerate.

Source

Thrown at src/poetry/packages/locker.py:356

            # of the [tool.poetry] section at top level!
            relevant_content = relevant_poetry_content

        return sha256(json.dumps(relevant_content, sort_keys=True).encode()).hexdigest()

    def _get_lock_data(self) -> dict[str, Any]:
        if not self.lock.exists():
            raise RuntimeError("No lockfile found. Unable to read locked packages")

        with self.lock.open("rb") as f:
            try:
                lock_data = tomllib.load(f)
            except tomllib.TOMLDecodeError as e:
                raise RuntimeError(f"Unable to read the lock file ({e}).")

        # if the lockfile doesn't contain a metadata section at all,
        # it probably needs to be rebuilt completely
        if "metadata" not in lock_data:
            raise RuntimeError(
                "The lock file does not have a metadata entry.\n"
                "Regenerate the lock file with the `poetry lock` command."
            )

        metadata = lock_data["metadata"]
        if "lock-version" not in metadata:
            raise RuntimeError(
                "The lock file is not compatible with the current version of Poetry.\n"
                "Regenerate the lock file with the `poetry lock` command."
            )
        lock_version = Version.parse(metadata["lock-version"])
        current_version = Version.parse(self._VERSION)
        accepted_versions = parse_constraint(self._READ_VERSION_RANGE)
        lock_version_allowed = accepted_versions.allows(lock_version)
        if lock_version_allowed and current_version < lock_version:
            logger.warning(
                "The lock file might not be compatible with the current version of"
                " Poetry.\nUpgrade Poetry to ensure the lock file is read properly or,"

View on GitHub (pinned to 92b74dcfe3)

Solutions

Run `poetry lock` to regenerate a standards-compliant poetry.lock with the metadata table.
If regenerating is undesirable, inspect poetry.lock to confirm it is genuinely a Poetry lockfile and not from another tool.
Upgrade Poetry to the latest stable release before locking, so the generated metadata is current.

Example fix

// before: poetry.lock with no [metadata] section
[[package]]
name = "click"
version = "8.1.0"

// after
$ poetry lock

Defensive patterns

Strategy: validation

Validate before calling

import tomllib
from pathlib import Path

def lockfile_has_metadata(path: Path) -> bool:
    with path.open("rb") as f:
        data = tomllib.load(f)
    return "metadata" in data

Prevention

Always generate poetry.lock with a current Poetry version.
Do not copy lockfiles from other tools (pdm, pip-tools) under the poetry.lock name.
After any lockfile manipulation, verify the [metadata] table is intact.
Pin the Poetry version in CI to avoid schema drift.

When it happens

Trigger: Any locked-packages read on a poetry.lock that is valid TOML but missing the [metadata] table — e.g. a hand-authored stub, a file copied from another tool, or a lockfile generated by a very old pre-metadata Poetry version.

Common situations: Migrating from extremely old Poetry (<1.0) where the lock schema differed; committing a placeholder poetry.lock; a different tool (pip-tools, pdm) wrote a file named poetry.lock.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/7b03d20d06fe8568.json. Report an issue: GitHub.