What causes "You must pass exactly 1 value" in python-poetry/poetry?

Pass exactly one value, e.g. `poetry config certificates.foo.cert /path/to/ca.pem`.

python-poetry/poetry · error · ValueError

You must pass exactly 1 value

Error message

You must pass exactly 1 value

What it means

Raised by `poetry config certificates.<repo>.<cert|client-cert> <value>` when the number of positional values is not exactly one. The certificates handler at config.py:324-334 stores a single path (or boolean for `cert`) per call, so passing zero or multiple values is rejected. It guards the auth config source from writing a malformed certificates entry.

Source

Thrown at src/poetry/console/commands/config.py:334

            if self.option("unset"):
                config.auth_config_source.remove_property(
                    ["certificates", repository, key]
                )

                return 0

            if len(values) == 1:
                new_value: str | bool = values[0]

                if key == "cert" and boolean_validator(values[0]):
                    new_value = boolean_normalizer(values[0])

                config.auth_config_source.add_property(
                    ["certificates", repository, key], new_value
                )
            else:
                raise ValueError("You must pass exactly 1 value")

            return 0

        # handle build config settings
        m = re.match(r"installer\.build-config-settings\.([^.]+)", self.argument("key"))
        if m:
            key = f"installer.build-config-settings.{canonicalize_name(m.group(1))}"

            if self.option("unset"):
                config.config_source.remove_property(key)
                return 0

            try:
                settings = config.config_source.get_property(key)
            except PropertyNotFoundError:
                settings = {}

            for value in values:

View on GitHub (pinned to 92b74dcfe3)

Solutions

Pass exactly one value, e.g. `poetry config certificates.foo.cert /path/to/ca.pem`.
Quote paths containing spaces: `poetry config certificates.foo.cert "/path with spaces/ca.pem"`.
To remove the entry use `poetry config --unset certificates.foo.cert` instead of passing no value.

Example fix

# before
poetry config certificates.foo.cert
# after
poetry config certificates.foo.cert /etc/ssl/certs/foo-ca.pem

Defensive patterns

Strategy: validation

Validate before calling

import sys
values = sys.argv  # the positional values after the key
if len(values) != 1:
    raise SystemExit("pass exactly one value, e.g. certificates.<repo>.cert /path/to/cert")

Type guard

def is_single_value(values: list[str]) -> bool:
    return isinstance(values, list) and len(values) == 1 and bool(values[0])

Prevention

Quote paths containing spaces so the shell passes a single token.
Use `poetry config --unset` to remove an entry rather than omitting the value.
Build the command from a validated list of arguments in scripts.

When it happens

Trigger: Running `poetry config certificates.foo.cert` with no value, or `poetry config certificates.foo.cert a b` with two values. Also triggered by passing the value via a malformed shell expansion that yields zero tokens.

Common situations: Forgetting to append the path argument; copy-pasting a command that included two cert paths; shell quoting that splits a single path with spaces into multiple values.

Related errors

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