python-poetry/poetry · error · ValueError

Extra [{extra}] is not specified.

Error message

Extra [{extra}] is not specified.

What it means

Raised by Installer._do_refresh at src/poetry/installation/installer.py:188-190 when an --extras value passed to `poetry install` does not correspond to any extra defined on the root project (self._package.extras). ValueError. The refresh path re-resolves the existing lock.

Source

Thrown at src/poetry/installation/installer.py:190

        return self

    def whitelist(self, packages: Iterable[str]) -> Installer:
        self._whitelist = [canonicalize_name(p) for p in packages]

        return self

    def extras(self, extras: list[str]) -> Installer:
        self._extras = [canonicalize_name(extra) for extra in extras]

        return self

    def _do_refresh(self) -> int:
        from poetry.puzzle.solver import Solver

        # Checking extras
        for extra in self._extras:
            if extra not in self._package.extras:
                raise ValueError(f"Extra [{extra}] is not specified.")

        locked_repository = self._locker.locked_repository()
        solver = Solver(
            self._package,
            self._pool,
            locked_repository.packages,
            locked_repository.packages,
            self._io,
        )

        # Always re-solve directory dependencies, otherwise we can't determine
        # if anything has changed (and the lock file contains an invalid version).
        use_latest = [
            p.name for p in locked_repository.packages if p.source_type == "directory"
        ]

        with solver.provider.use_source_root(
            source_root=self._env.path.joinpath("src")

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. List defined extras: inspect [tool.poetry.extras] in pyproject.toml.
2. Correct the extra name on the command line (extras are case-insensitive but must exist).
3. Add the missing extra to pyproject.toml if the intent is to install a new optional group.

Example fix

# before
$ poetry install --refresh --extras testng
ValueError: Extra [testng] is not specified.

# fix command
$ poetry install --refresh --extras testing

# or add the extra
[tool.poetry.extras]
testng = ["pytest"]

from poetry.utils.helpers import canonicalize_name

def validate_extras(requested, declared):
    declared_set = {canonicalize_name(e) for e in declared}
    for extra in requested:
        if canonicalize_name(extra) not in declared_set:
            raise ValueError(f'Extra [{canonicalize_name(extra)}] is not specified.')

try:
    installer.whitelist([pkg])  # or run()
except ValueError as e:
    if 'Extra [' in str(e):
        # prompt user / list available extras from pyproject before retrying
        raise SystemExit(f'Unknown extra: {e}') from e
    raise

When it happens

Trigger: Running `poetry install --refresh --extras foo` where 'foo' is not declared under [tool.poetry.extras] in pyproject.toml. The check canonicalizes the requested extra and looks it up in the project's extras mapping.

Common situations: Typo in the extra name, an extra that was renamed/removed from pyproject.toml, or running the command in a project that has no extras defined at all.

Related errors

• pyproject.toml changed significantly since poetry.lock was l
• Missing [url] in source {name!r}.
• Bad script ({name}): script needs to specify a function with
• You can only specify one package when using the --extras opt
• You can only add optional dependencies to the main group

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