python-poetry/poetry · error · RuntimeError

The lock file is not compatible with the current version of

Error message

The lock file is not compatible with the current version of Poetry.
Regenerate the lock file with the `poetry lock` command.

What it means

Raised by Locker._get_lock_data() when the lockfile has a [metadata] table but that table lacks the 'lock-version' field. lock-version is how Poetry negotiates schema compatibility; without it the file is treated as an unrecognised/legacy format. The message directs the user to regenerate.

Source

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

            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,"
                " alternatively, regenerate the lock file with the `poetry lock`"
                " command."
            )
        elif not lock_version_allowed:
            raise RuntimeError(
                "The lock file is not compatible with the current version of Poetry.\n"
                "Upgrade Poetry to be able to read the lock file or, alternatively, "

View on GitHub (pinned to 92b74dcfe3)

Solutions

Run `poetry lock` to rewrite poetry.lock with the current schema including lock-version.
Upgrade Poetry (`poetry self update`) so the regenerated lockfile uses the latest lock-version.
If preserving pins matters, run `poetry lock --no-update` to re-emit metadata without re-resolving.

Example fix

// before: [metadata] without lock-version
[metadata]
content-hash = "abc123"

// after
$ poetry lock --no-update
# produces:
# [metadata]
# lock-version = "2.1"
# python-versions = ">=3.9"
# content-hash = "abc123"

Defensive patterns

Strategy: validation

Validate before calling

import tomllib
from pathlib import Path

def lockfile_has_lock_version(path: Path) -> bool:
    with path.open("rb") as f:
        data = tomllib.load(f)
    return "lock-version" in data.get("metadata", {})

Prevention

Use a recent stable Poetry to generate lockfiles.
Run `poetry lock --no-update` after upgrading Poetry to refresh metadata without re-resolving.
Add a CI check asserting metadata.lock-version is present.
Educate the team not to strip metadata fields when editing.

When it happens

Trigger: A poetry.lock whose [metadata] table exists (so error 62 is bypassed) but was authored without the lock-version key — typically an old-format lockfile or one edited to remove the field. Triggered by install/show/update --lock.

Common situations: Lockfile produced by Poetry 1.x early schema before lock-version was standardised; manual deletion of the lock-version line; a partial write that truncated the metadata table.

Related errors

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