ultralytics/ultralytics · error · ValueError

'{k}={v}' is invalid. Valid '{k}' values are {QUANTIZE_VALID

Error message

'{k}={v}' is invalid. Valid '{k}' values are {QUANTIZE_VALID_VALUES}. See {QUANTIZE_DOCS_URL}

What it means

The `quantize` key canonicalizes numeric precisions (8/16/32) and w-notation (e.g. w8, w16) through the QUANTIZE_ALIASES map into a scheme. A value that matches no alias (after lowercasing and str()) raises ValueError in hard mode; in soft mode an unknown value is silently left as-is. Unset (None) stays None meaning FP32. The message points at QUANTIZE_VALID_VALUES and the docs URL.

Source

Thrown at ultralytics/cfg/__init__.py:494

                        f"'{k}' must be a bool (i.e. '{k}=True' or '{k}=False')"
                    )
                cfg[k] = bool(v)
            elif k in CFG_STR_KEYS and not isinstance(v, str):
                if hard:
                    raise TypeError(f"'{k}={v}' is of invalid type {type(v).__name__}. '{k}' must be a str.")
                cfg[k] = str(v)
            elif k == "compile" and not isinstance(v, (bool, str)):  # False=off, True="default", or a mode string
                if hard:
                    raise TypeError(
                        f"'{k}={v}' is of invalid type {type(v).__name__}. "
                        f"'{k}' must be a bool or str (i.e. '{k}=True' or '{k}=max-autotune')"
                    )
                cfg[k] = bool(v)
            elif k == "quantize":  # canonicalize 8/16/32 or w-notation to a scheme (unset stays None for FP32)
                scheme = QUANTIZE_ALIASES.get(str(v).lower())
                if scheme is None:
                    if hard:
                        raise ValueError(
                            f"'{k}={v}' is invalid. Valid '{k}' values are {QUANTIZE_VALID_VALUES}. "
                            f"See {QUANTIZE_DOCS_URL}"
                        )
                else:
                    cfg[k] = scheme


def get_save_dir(args: SimpleNamespace, name: str | None = None) -> Path:
    """Return the directory path for saving outputs, derived from arguments or default settings.

    Args:
        args (SimpleNamespace): Namespace object containing configurations such as 'project', 'name', 'task', 'mode',
            and 'save_dir'.
        name (str | None): Optional name for the output directory. If not provided, it defaults to 'args.name' or the
            'args.mode'.

    Returns:
        (Path): Directory path where outputs should be saved.

View on GitHub (pinned to 0449ea011c)

Solutions

1. Use one of the values listed in the error (QUANTIZE_VALID_VALUES), e.g. quantize=8/16/32 or 'w8'/'w16'.
2. Omit quantize (or pass None) for default FP32.
3. Check the linked docs page (QUANTIZE_DOCS_URL in the message) for the current alias table before inventing notation.
4. Verify the target export format actually supports the requested scheme.

Example fix

# before
model.export(format="onnx", quantize="int4")

# after
model.export(format="onnx", quantize="w8")  # use a supported alias

from ultralytics.cfg import QUANTIZE_ALIASES  # alias map used by check_cfg

valid = set(QUANTIZE_ALIASES) | {None}
if cfg.get("quantize") not in valid and str(cfg.get("quantize")).lower() not in QUANTIZE_ALIASES:
    raise ValueError(f"quantize must be one of {sorted(QUANTIZE_ALIASES)} or None")

def is_valid_quantize(v) -> bool:
    from ultralytics.cfg import QUANTIZE_ALIASES
    return v is None or str(v).lower() in QUANTIZE_ALIASES

try:
    model.export(format="onnx", quantize=scheme)
except ValueError as e:
    if "Valid 'quantize'" in str(e):
        scheme = "w8"  # or None for FP32
        model.export(format="onnx", quantize=scheme)
    else:
        raise

When it happens

Trigger: export(quantize='int4'), train/predict overrides with quantize='fp8', quantize='q4_k_m' or other values not in QUANTIZE_ALIASES, passed through hard validation (API overrides, cfg YAML). Case-insensitive: 'W8' works, 'int4' does not if 4-bit is unsupported.

Common situations: Requesting precisions the build does not support (4-bit, fp8); mixing GGLM/GGUF quantization mnemonics (q4_0) with ultralytics quantize syntax; typos like 'w8a8' when only plain w-notation is aliased.

Related errors

• '{k}={v}' is an invalid value. '{k}' must be >= {CFG_INT_MIN
• '{k}={v}' is of invalid type {type(v).__name__}. Valid '{k}'
• '{k}={v}' is of invalid type {type(v).__name__}. '{k}' must
• '{k}={v}' is of invalid type {type(v).__name__}. '{k}' must
• '{k}={v}' is of invalid type {type(v).__name__}. '{k}' must

AI-assisted analysis of ultralytics/ultralytics@0449ea011c (2026-08-15). Data as JSON: /api/errors/35a97af45061a0fe. Report an issue: GitHub.