What causes "Number of experts must be divisible by model parallelism" in deepseek-ai/DeepSeek-V3?

Use --model-parallel in {2,4,8,16,32,64} for n-experts 256

deepseek-ai/DeepSeek-V3 · error · AssertionError

Number of experts must be divisible by model parallelism

Error message

Number of experts must be divisible by model parallelism

What it means

Thrown in convert.py's __main__ (inference/convert.py:95): experts are distributed round-robin into n_experts // model_parallel local experts per shard file, so --n-experts (256 for DeepSeek-V3 R1/V3) must be divisible by --model-parallel. This is a CLI-level precondition checked before main() runs.

Source

Thrown at inference/convert.py:95

    os.makedirs(save_path, exist_ok=True)

    for i in trange(mp):
        save_file(state_dicts[i], os.path.join(save_path, f"model{i}-mp{mp}.safetensors"))

    for file_path in glob(os.path.join(hf_ckpt_path, "*token*")):
        new_file_path = os.path.join(save_path, os.path.basename(file_path))
        shutil.copyfile(file_path, new_file_path)


if __name__ == "__main__":
    parser = ArgumentParser()
    parser.add_argument("--hf-ckpt-path", type=str, required=True)
    parser.add_argument("--save-path", type=str, required=True)
    parser.add_argument("--n-experts", type=int, required=True)
    parser.add_argument("--model-parallel", type=int, required=True)
    args = parser.parse_args()
    assert args.n_experts % args.model_parallel == 0, "Number of experts must be divisible by model parallelism"
    main(args.hf_ckpt_path, args.save_path, args.n_experts, args.model_parallel)

View on GitHub (pinned to 9b4e9788e4)

Solutions

Use --model-parallel in {2,4,8,16,32,64} for n-experts 256
Set --n-experts to the checkpoint's true routed expert count (256 for DeepSeek-V3/R1)
Keep this mp identical to the inference world_size used at generate time

Example fix

# before
python convert.py --hf-ckpt-path hf/ --save-path out/ --n-experts 256 --model-parallel 6

# after
python convert.py --hf-ckpt-path hf/ --save-path out/ --n-experts 256 --model-parallel 8

Defensive patterns

Strategy: validation

Validate before calling

n_experts, mp = 256, 8
assert n_experts % mp == 0, (
    f"n_experts={n_experts} not divisible by model_parallel={mp}; pick 2/4/8/16"
)

Type guard

def experts_divide(n_experts: int, mp: int) -> bool:
    return n_experts % mp == 0

Prevention

Pass --n-experts exactly matching the checkpoint (256 for DeepSeek-V3/R1)
Select mp from divisors of the expert count and equal to your GPU count
Script the full convert+launch pipeline so the two values cannot drift

When it happens

Trigger: Running convert.py with e.g. --n-experts 256 --model-parallel 6 (256 % 6 != 0), or --n-experts values from a different model variant than the mp degree chosen.

Common situations: Picking mp equal to available GPUs without considering expert count; mismatching --n-experts with the actual checkpoint (must equal the checkpoint's routed expert count, e.g. 256, not 257/128).

Related errors

AI-assisted analysis of deepseek-ai/DeepSeek-V3@9b4e9788e4 (2026-08-14). Data as JSON: /api/errors/9ccf8d293df99084. Report an issue: GitHub.