python-poetry/poetry · error · ValueError

Invalid format: {fmt}

Error message

Invalid format: {fmt}

What it means

Raises ValueError in BuildOptions.__post_init__() when a build format string is not one of the keys in BUILD_FORMATS (which by default contains only 'sdist' and 'wheel', extendable by plugins). BuildOptions is constructed from the --format (-f) CLI option; the dataclass validator rejects unknown formats immediately after construction.

Source

Thrown at src/poetry/console/commands/build.py:43

    from cleo.io.io import IO

    from poetry.poetry import Poetry
    from poetry.utils.env import Env

DistributionType = Literal["sdist", "wheel"]


@dataclasses.dataclass(frozen=True)
class BuildOptions:
    clean: bool
    formats: list[DistributionType]
    output: str
    config_settings: dict[str, Any] = dataclasses.field(default_factory=dict)

    def __post_init__(self) -> None:
        for fmt in self.formats:
            if fmt not in BUILD_FORMATS:
                raise ValueError(f"Invalid format: {fmt}")


class BuildHandler:
    def __init__(self, poetry: Poetry, env: Env, io: IO) -> None:
        self.poetry = poetry
        self.env = env
        self.io = io

    def _build(
        self,
        fmt: DistributionType,
        executable: Path,
        target_dir: Path,
        config_settings: dict[str, Any],
    ) -> None:
        builder = BUILD_FORMATS[fmt]

        builder(

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Use 'sdist', 'wheel', or omit -f to build both formats (the default 'all' expands to sdist+wheel).
2. If using a plugin-provided format, verify the plugin is installed and registered so it extends BUILD_FORMATS.

Example fix

# before (error)
poetry build -f tar.gz
# after
poetry build -f wheel
# or simply
poetry build

from poetry.masonry.builders import BUILD_FORMATS

def validate_format(fmt: str) -> None:
    if fmt not in BUILD_FORMATS:
        valid = ", ".join(BUILD_FORMATS)
        raise ValueError(f"Invalid format '{fmt}'. Valid: {valid}")

from poetry.masonry.builders import BUILD_FORMATS

def is_valid_format(fmt: str) -> bool:
    return fmt in BUILD_FORMATS

When it happens

Trigger: Running `poetry build -f tarball` or any format string not in BUILD_FORMATS. The format comes from _prepare_formats() which passes through any non-'all' string verbatim, so any misspelled or unsupported format reaches this check.

Common situations: Typo in the format name (e.g. 'sdists', 'wheels'), using a format name from a plugin that isn't installed/enabled, or passing 'all' with extra whitespace.

Related errors

• Invalid config setting format: {config_setting}. Config sett
• Key {'.'.join(keys)} not in config
• Key {'.'.join(keys)} not in config
• 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/fbd0ce0d7a147b60.json. Report an issue: GitHub.