Poetry lockfile drift

What this failure means

Poetry is installing from a lockfile that no longer matches pyproject.toml, so dependency resolution fails before the environment is usable.

Symptoms

Faultline looks for one or more of these log fragments:

poetry.lock is not consistent with pyproject.toml
Run `poetry lock [--no-update]` to fix it.
version solving failed

Diagnosis

The project manifest and poetry.lock have drifted apart. Poetry warns that the lockfile is stale, then fails to solve or install the dependency set that the project now declares.

Any later import error is usually a downstream effect of the failed install, not the primary root cause.

Fix steps

1. Regenerate the lockfile from the current manifest:

   poetry lock --no-update
   

2. If resolution still fails, update the incompatible dependency constraint in pyproject.toml and re-run poetry lock.

3. Commit both pyproject.toml and poetry.lock together.

4. Recreate the virtual environment if Poetry cached a broken environment from an earlier failed install.

Validation

• Run poetry install from a clean checkout.
• Confirm Poetry no longer warns that poetry.lock is inconsistent with pyproject.toml.
• Re-run the failing Python command after the install completes successfully.

Why it matters

A stale Poetry lockfile turns a reproducible Python environment into a misleading partial install. The first visible failure may be an import error, but the real defect is manifest-lock drift.

Prevention

• Update poetry.lock in the same change as every manifest edit.
• Use one team-standard Poetry version in local development and CI.
• Add a CI check that runs poetry install from a clean environment on dependency changes.

Try it locally

poetry install
poetry lock --no-update
poetry install

How Faultline detects it

Use faultline explain poetry-lockfile-drift to see the full playbook.

faultline analyze build.log
faultline explain poetry-lockfile-drift

Generated from playbooks/bundled/log/build/poetry-lockfile-drift.yaml. Do not edit directly.