scrapy/scrapy · error · ValueError

Unknown {setting_name} value: {setting}

Error message

Unknown {setting_name} value: {setting}

What it means

Error "Unknown {setting_name} value: {setting}" thrown in scrapy/scrapy.

Source

Thrown at scrapy/utils/ssl.py:44

logger = logging.getLogger(__name__)

_T = TypeVar("_T")


# common


def _get_tls_version_limit(
    settings: BaseSettings, setting_name: str, converter: Callable[[str], _T]
) -> _T | None:
    setting: str | None = settings[setting_name]
    if setting is None:
        return None
    try:
        return converter(setting)
    except Exception as ex:
        raise ValueError(f"Unknown {setting_name} value: {setting}") from ex


def _get_tls_version_limits(
    settings: BaseSettings, converter: Callable[[str], _T]
) -> tuple[_T | None, _T | None]:
    return (
        _get_tls_version_limit(settings, "DOWNLOAD_TLS_MIN_VERSION", converter),
        _get_tls_version_limit(settings, "DOWNLOAD_TLS_MAX_VERSION", converter),
    )


# stdlib ssl module utils

_STDLIB_VERSION_MAP: dict[str, ssl.TLSVersion] = {
    "TLSv1.0": ssl.TLSVersion.TLSv1,
    "TLSv1.1": ssl.TLSVersion.TLSv1_1,
    "TLSv1.2": ssl.TLSVersion.TLSv1_2,
    "TLSv1.3": ssl.TLSVersion.TLSv1_3,

View on GitHub (pinned to 06af687662)

Solutions

1. Set the DOWNLOADER_CLIENT_TLS_MIN_VERSION or DOWNLOADER_CLIENT_TLS_MAX_VERSION setting to a valid TLS version name accepted by OpenSSLVersion, e.g. 'TLSv1.2' or 'TLSv1.3'.
2. Check the setting value for typos or unsupported values such as 'SSLv3' on platforms where it is unavailable, and use one of the TLSVersion constants instead.
3. Remove the setting entirely if you do not need to restrict TLS versions, so Scrapy uses the OpenSSL defaults.

When it happens

Trigger: Raised when the DOWNLOAD_TLS_MIN_VERSION or DOWNLOAD_TLS_MAX_VERSION setting contains a value that the TLS version converter cannot parse. The setting value is validated at startup when the TLS version limits are computed from settings; any string not in the supported set (e.g. 'TLSv1.2', 'TLSv1.3') triggers this ValueError. Defense: validate DOWNLOAD_TLS_MIN_VERSION/DOWNLOAD_TLS_MAX_VERSION values against the supported TLS version names in configuration before running the crawler.

Common situations: See trigger scenarios.

AI-assisted analysis of scrapy/scrapy@06af687662 (2026-08-15). Data as JSON: /api/errors/60a0a3d080b28bc5. Report an issue: GitHub.