python-poetry/poetry · warning · RuntimeError

You can not combine a setting value with --unset

Error message

You can not combine a setting value with --unset

What it means

Raises RuntimeError in ConfigCommand.handle() when the user provides both a setting value AND the --unset flag. These are mutually exclusive: --unset removes a setting, while providing a value sets it. The check at line 160-161 is `if self.argument('value') and self.option('unset')`.

Source

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

        if self.option("local"):
            config.set_config_source(FileConfigSource(local_config_file))

        if not config_file.exists():
            config_file.path.parent.mkdir(parents=True, exist_ok=True)
            config_file.path.touch(mode=0o0600)

        if self.option("list"):
            self._list_configuration(config.all(), config.raw())

            return 0

        setting_key = self.argument("key")
        if not setting_key:
            return 0

        if self.argument("value") and self.option("unset"):
            raise RuntimeError("You can not combine a setting value with --unset")

        repo_regex = r"^repos?(?:itories)?(?:\.(.+?)(?:\.(url))?)?$"

        # show the value if no value is provided
        if not self.argument("value") and not self.option("unset"):
            if setting_key.split(".")[0] in self.LIST_PROHIBITED_SETTINGS:
                raise ValueError(f"Expected a value for {setting_key} setting.")

            value: str | dict[str, Any] | list[str]

            if m := re.match(
                r"installer\.build-config-settings(\.([^.]+))?", self.argument("key")
            ):
                if not m.group(1):
                    if value := config.get("installer.build-config-settings"):
                        self._list_configuration(value, value)
                    else:
                        self.line("No packages configured with build config settings.")

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. To unset a setting, omit the value: `poetry config virtualenvs.create --unset`.
2. To set a value, omit --unset: `poetry config virtualenvs.create true`.

Example fix

# before (error)
poetry config virtualenvs.create true --unset
# after (to unset)
poetry config virtualenvs.create --unset
# after (to set)
poetry config virtualenvs.create true

def validate_config_args(value, unset: bool) -> None:
    if value and unset:
        raise ValueError("Cannot combine a setting value with --unset; choose one or the other")

def are_config_args_valid(value, unset: bool) -> bool:
    return not (value and unset)

When it happens

Trigger: Running `poetry config virtualenvs.create true --unset` — passing a value argument alongside --unset.

Common situations: User accidentally leaves a stale value in the command or misunderstands that --unset takes no value.

Related errors

• Add the --all option if you want to clear all cache entries
• Only specifying the package name is not yet supported. Add a
• You cannot remove the [repositories] section
• You must pass the url. Example: poetry config repositories.f
• Expected one or two arguments (username, password), got {len

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