hiyouga/LlamaFactory · error · ValueError

`recompute_method` must be 'uniform' or 'block'.

Error message

`recompute_method` must be 'uniform' or 'block'.

What it means

Raised in MegatronBridgeArguments.__post_init__ (megatron_bridge_args.py:168) when recompute_method is set to a string other than 'uniform' or 'block'. The method controls how recompute_num_layers layers are chosen for recomputation: 'uniform' spreads them evenly across transformer layers, 'block' chunks them contiguously per pipeline stage. It is validated as an exact lowercase string and only matters when recompute_granularity is 'full'.

Source

Thrown at src/llamafactory/hparams/megatron_bridge_args.py:168

    )

    def __post_init__(self) -> None:
        if self.tensor_model_parallel_size < 1:
            raise ValueError("`tensor_model_parallel_size` must be >= 1.")
        if self.pipeline_model_parallel_size < 1:
            raise ValueError("`pipeline_model_parallel_size` must be >= 1.")
        if self.expert_model_parallel_size < 1:
            raise ValueError("`expert_model_parallel_size` must be >= 1.")
        if self.context_parallel_size < 1:
            raise ValueError("`context_parallel_size` must be >= 1.")
        if self.virtual_pipeline_model_parallel_size is not None and self.virtual_pipeline_model_parallel_size < 1:
            raise ValueError("`virtual_pipeline_model_parallel_size` must be >= 1 when set.")
        if self.sequence_parallel and self.tensor_model_parallel_size <= 1:
            raise ValueError("`sequence_parallel` requires `tensor_model_parallel_size` > 1.")
        if self.recompute_granularity is not None and self.recompute_granularity not in ("full", "selective"):
            raise ValueError("`recompute_granularity` must be 'full' or 'selective'.")
        if self.recompute_method is not None and self.recompute_method not in ("uniform", "block"):
            raise ValueError("`recompute_method` must be 'uniform' or 'block'.")
        if self.recompute_num_layers is not None and self.recompute_num_layers < 1:
            raise ValueError("`recompute_num_layers` must be >= 1 when set.")
        if self.moe_token_dispatcher_type is not None and self.moe_token_dispatcher_type not in (
            "allgather",
            "alltoall",
            "flex",
        ):
            raise ValueError("`moe_token_dispatcher_type` must be 'allgather', 'alltoall', or 'flex'.")

        if isinstance(self.extra_config, str):
            config_str = self.extra_config.strip()
            if config_str.startswith("{"):
                self.extra_config = _convert_str_dict(json.loads(config_str))
            else:
                self.extra_config = config_str

    def load_extra_config(self) -> dict:
        if self.extra_config is None:

View on GitHub (pinned to f28afaf635)

Solutions

1. Use exactly 'uniform' or 'block' (lowercase)
2. Pair it with recompute_granularity: full and a positive recompute_num_layers
3. Remove recompute_method if you do not need deterministic block/uniform placement

Example fix

# before
recompute_method: blocks

# after
recompute_granularity: full
recompute_method: uniform
recompute_num_layers: 1

if cfg.get('recompute_method') not in (None, 'uniform', 'block'):
    raise SystemExit(f"bad recompute_method: {cfg['recompute_method']!r}")

def is_valid_recompute_method(v: str | None) -> bool:
    return v in (None, 'uniform', 'block')

When it happens

Trigger: Setting recompute_method: uniform/block with wrong casing or a typo ('blocks', 'Uniform'); providing a Megatron-core enum name like 'RecomputeMethod.UNIFORM' as a string; setting the method without setting recompute_granularity/full first.

Common situations: Transcribing values from Megatron-LM launch scripts; LLM-assisted configs inventing plausible values; refactors that renamed the field's accepted vocabulary.

Related errors

• `recompute_granularity` must be 'full' or 'selective'.
• `recompute_num_layers` must be >= 1 when set.
• `virtual_pipeline_model_parallel_size` must be >= 1 when set
• `sequence_parallel` requires `tensor_model_parallel_size` >
• `moe_token_dispatcher_type` must be 'allgather', 'alltoall',

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/4e810c939f28316f. Report an issue: GitHub.