facebookresearch/detectron2 · error · ValueError

bias_lr_factor requires base_lr

Error message

bias_lr_factor requires base_lr

What it means

get_default_optimizer_params needs a scalar base learning rate to compute per-bias-parameter LR overrides. If bias_lr_factor is set but base_lr is None (weight_decay path where LR comes from overrides), there is no LR to multiply.

Source

Thrown at detectron2/solver/build.py:192

    Example:
    ::
        torch.optim.SGD(get_default_optimizer_params(model, weight_decay_norm=0),
                       lr=0.01, weight_decay=1e-4, momentum=0.9)
    """
    if overrides is None:
        overrides = {}
    defaults = {}
    if base_lr is not None:
        defaults["lr"] = base_lr
    if weight_decay is not None:
        defaults["weight_decay"] = weight_decay
    bias_overrides = {}
    if bias_lr_factor is not None and bias_lr_factor != 1.0:
        # NOTE: unlike Detectron v1, we now by default make bias hyperparameters
        # exactly the same as regular weights.
        if base_lr is None:
            raise ValueError("bias_lr_factor requires base_lr")
        bias_overrides["lr"] = base_lr * bias_lr_factor
    if weight_decay_bias is not None:
        bias_overrides["weight_decay"] = weight_decay_bias
    if len(bias_overrides):
        if "bias" in overrides:
            raise ValueError("Conflicting overrides for 'bias'")
        overrides["bias"] = bias_overrides
    if lr_factor_func is not None:
        if base_lr is None:
            raise ValueError("lr_factor_func requires base_lr")
    norm_module_types = (
        torch.nn.BatchNorm1d,
        torch.nn.BatchNorm2d,
        torch.nn.BatchNorm3d,
        torch.nn.SyncBatchNorm,
        # NaiveSyncBatchNorm inherits from BatchNorm2d
        torch.nn.GroupNorm,
        torch.nn.InstanceNorm1d,

View on GitHub (pinned to a2f4a8771a)

Solutions

1. Pass base_lr (e.g. cfg.SOLVER.BASE_LR) to get_default_optimizer_params/build_optimizer
2. Drop bias_lr_factor (set to None or 1.0) so no bias LR scaling is requested
3. Supply the bias LR directly via overrides={'bias': {'lr': ...}} instead

Example fix

# before
params = get_default_optimizer_params(model, bias_lr_factor=2.0, weight_decay=1e-4)
# after
params = get_default_optimizer_params(model, base_lr=cfg.SOLVER.BASE_LR, bias_lr_factor=2.0, weight_decay=1e-4)

if bias_lr_factor is not None and bias_lr_factor != 1.0:
    assert base_lr is not None, 'bias_lr_factor requires base_lr (set cfg.SOLVER.BASE_LR)'

try:
    params = get_default_optimizer_params(model, base_lr=None, bias_lr_factor=f)
except ValueError as e:
    raise ValueError(f'optimizer build failed: {e}; pass base_lr') from e

When it happens

Trigger: Calling build_optimizer/get_default_optimizer_params with bias_lr_factor != 1.0 and base_lr=None, e.g. when SOLVER.BASE_LR is unset while a custom optimizer passes weight_decay params only.

Common situations: Custom optimizer builders that pass weight_decay but not base_lr; configs that rely on per-module lr overrides while also setting bias_lr_factor.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• lr_factor_func requires base_lr
• Class with @configurable must have a 'from_config' classmeth
• {name} must take 'cfg' as the first argument!
• total_batch_size and single_gpu_batch_size are mutually inco
• Unknown training sampler: {}

AI-assisted analysis of facebookresearch/detectron2@a2f4a8771a (2026-08-27). Data as JSON: /api/errors/b1b94b9b50a5dc88. Report an issue: GitHub.