OpenBMB/VoxCPM · error · ValueError

You must provide hf_model_id

Error message

You must provide hf_model_id

What it means

VoxCPM.from_pretrained requires a Hugging Face repo id (or local dir path); an empty/None hf_model_id with no resolvable default raises immediately.

Source

Thrown at src/voxcpm/core.py:153

                provided without lora_config, a default config will be created with
                enable_lm=True and enable_dit=True.
            lora_weights_path: Path to pre-trained LoRA weights (.pth file or directory
                containing lora_weights.ckpt). If provided, LoRA weights will be loaded
                after model initialization.
        Kwargs:
            Additional keyword arguments passed to the ``VoxCPM`` constructor.

        Returns:
            VoxCPM: Initialized instance whose ``voxcpm_model_path`` points to
            the downloaded snapshot directory.

        Raises:
            ValueError: If neither a valid ``hf_model_id`` nor a resolvable
                ``hf_model_id`` is provided.
        """
        repo_id = hf_model_id
        if not repo_id:
            raise ValueError("You must provide hf_model_id")

        # Load from local path if provided
        if os.path.isdir(repo_id):
            local_path = repo_id
        else:
            # Otherwise, try from_pretrained (Hub); exit on failure
            local_path = snapshot_download(
                repo_id=repo_id,
                cache_dir=cache_dir,
                local_files_only=local_files_only,
            )

        return cls(
            voxcpm_model_path=local_path,
            zipenhancer_model_path=zipenhancer_model_id if load_denoiser else None,
            enable_denoiser=load_denoiser,
            optimize=optimize,
            device=device,

View on GitHub (pinned to f5a1c6a6b9)

Solutions

1. Pass an explicit hf_model_id, e.g. from_pretrained('openbmb/VoxCPM-0.5B')
2. If it should come from config/env, verify that value is actually populated before calling
3. For local checkpoints pass the directory path as hf_model_id

Example fix

# before
model = VoxCPM.from_pretrained(hf_model_id=None)
# after
model = VoxCPM.from_pretrained(hf_model_id="openbmb/VoxCPM-0.5B")

if not hf_model_id:
    hf_model_id = os.environ.get("VOXCPM_MODEL", "openbmb/VoxCPM-0.5B")

When it happens

Trigger: Calling from_pretrained() with hf_model_id=None or '' when no default model is configured.

Common situations: Omitting the model argument expecting a default, passing an empty string from a config/env var that was never set, or variable-name mixups (e.g. passing model_id keyword the function doesn't accept).

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.

AI-assisted analysis of OpenBMB/VoxCPM@f5a1c6a6b9 (2026-08-27). Data as JSON: /api/errors/ddb58d9505d51905. Report an issue: GitHub.