facebookresearch/detectron2 · error · ValueError

lr_factor_func requires base_lr

Error message

lr_factor_func requires base_lr

What it means

An lr_factor_func (per-module LR multiplier function) needs the base LR to scale parameters; if base_lr is None the multiplier cannot be applied, so get_default_optimizer_params raises.

Source

Thrown at detectron2/solver/build.py:202

        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,
        torch.nn.InstanceNorm2d,
        torch.nn.InstanceNorm3d,
        torch.nn.LayerNorm,
        torch.nn.LocalResponseNorm,
    )
    params: List[Dict[str, Any]] = []
    memo: Set[torch.nn.parameter.Parameter] = set()
    for module_name, module in model.named_modules():
        for module_param_name, value in module.named_parameters(recurse=False):
            if not value.requires_grad:

View on GitHub (pinned to a2f4a8771a)

Solutions

1. Pass base_lr=cfg.SOLVER.BASE_LR to build_optimizer/get_default_optimizer_params
2. Set cfg.SOLVER.BASE_LR in the config
3. Remove lr_factor_func if per-module scaling is not needed

Example fix

# before
build_optimizer(cfg, model, lr_factor_func=lr_multiplier)
# after
build_optimizer(cfg, model, base_lr=cfg.SOLVER.BASE_LR, lr_factor_func=lr_multiplier)

if lr_factor_func is not None:
    assert base_lr is not None, 'lr_factor_func requires base_lr'

When it happens

Trigger: Passing lr_factor_func (e.g. LRDetectionHeadMultiplier or LingUNetMultipliers) to build_optimizer while base_lr is None.

Common situations: Custom optimizers that set per-module LR factors via overrides instead of SOLVER.BASE_LR, leaving base_lr unset.

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

• bias_lr_factor requires base_lr
• Conflicting overrides for 'bias'
• Cannot match one checkpoint key to multiple keys in the mode
• Class with @configurable must have a 'from_config' classmeth
• {name} must take 'cfg' as the first argument!

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