python-poetry/poetry · error · ValueError

Invalid build config setting '{value}'. It must be a valid J

Error message

Invalid build config setting '{value}'. It must be a valid JSON with each property a string or a list of strings.

What it means

Raised when setting `installer.build-config-settings.<name>` (config.py:339-361) and a value fails `build_config_setting_validator`. Each value must be a JSON object whose properties are strings or lists of strings, matching PEP 517 config-settings semantics. Poetry stores them verbatim to forward to build backends.

Source

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

        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:
                if build_config_setting_validator(value):
                    config_settings = build_config_setting_normalizer(value)
                    for setting_name, item in config_settings.items():
                        settings[setting_name] = item
                else:
                    raise ValueError(
                        f"Invalid build config setting '{value}'. "
                        "It must be a valid JSON with each property a string or a list of strings."
                    )

            config.config_source.add_property(key, settings)

            return 0

        raise ValueError(f"Setting {self.argument('key')} does not exist")

    def _handle_single_value(
        self,
        source: ConfigSource,
        key: str,
        callbacks: tuple[Any, Any],
        values: list[Any],
    ) -> int:
        validator, normalizer = callbacks

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Pass a JSON object with string or list-of-string values: `poetry config installer.build-config-settings.foo '{"--build-option": "--foo"}'`.
2. Validate the JSON with `python -c "import json,sys; json.loads(sys.argv[1])" '<value>'` before running the command.
3. Ensure no trailing commas or unquoted keys that TOML/JSON parsers would reject.

Example fix

# before
poetry config installer.build-config-settings.setuptools '{"--global-option": ["--with-num"]}'  # if value type wrong
# after
poetry config installer.build-config-settings.setuptools '{"--build-option": "--with-num"}'

import json
raw = '{"--build-option": "--foo"}'
obj = json.loads(raw)  # raises if not JSON
assert isinstance(obj, dict) and all(
    isinstance(v, (str, list)) and all(isinstance(x, str) for x in v)
    for v in obj.values()
), "values must be str or list[str]"

def is_valid_build_config_setting(raw: str) -> bool:
    try:
        obj = json.loads(raw)
    except (TypeError, ValueError):
        return False
    return isinstance(obj, dict) and all(
        isinstance(v, str) or (
            isinstance(v, list) and all(isinstance(x, str) for x in v)
        )
        for v in obj.values()
    )

When it happens

Trigger: Running `poetry config installer.build-config-settings.foo '{not json}'` or passing a JSON whose values are numbers/objects instead of strings or lists of strings.

Common situations: Trying to configure a build backend (setuptools, hatchling) with malformed config-settings; forgetting that the whole value must be a JSON object; passing `--config-setting` style `key=value` pairs instead of JSON.

Related errors

• Failed to install {requirements}.
• Key {'.'.join(keys)} not in config
• Key {'.'.join(keys)} not in config
• You must pass exactly 1 value
• Setting {self.argument('key')} does not exist

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