vllm-project/vllm · error · FileNotFoundError

FP8 scale file not found: {scale_path}

Error message

FP8 scale file not found: {scale_path}

What it means

After the FP8 option-combination checks, MultiModalConfig verifies the file existence of mm_encoder_fp8_scale_path with Path.is_file(). If the path does not point to an existing regular file, a FileNotFoundError is raised at config-validation time so a typo'd scale path never reaches the engine.

Source

Thrown at vllm/config/multimodal.py:341

            raise ValueError(
                "'mm_encoder_fp8_scale_path' and "
                "'mm_encoder_fp8_scale_save_path' require "
                "'mm_encoder_attn_dtype' to be 'fp8'."
            )
        if (
            self.mm_encoder_fp8_scale_path is not None
            and self.mm_encoder_fp8_scale_save_path is not None
        ):
            raise ValueError(
                "'mm_encoder_fp8_scale_save_path' cannot be used with "
                "'mm_encoder_fp8_scale_path' (saving requires dynamic scaling)."
            )

        # Validate file paths exist.
        if self.mm_encoder_fp8_scale_path is not None:
            scale_path = Path(self.mm_encoder_fp8_scale_path)
            if not scale_path.is_file():
                raise FileNotFoundError(f"FP8 scale file not found: {scale_path}")
        if self.mm_encoder_fp8_scale_save_path is not None:
            save_parent = Path(self.mm_encoder_fp8_scale_save_path).parent
            if not save_parent.is_dir():
                raise FileNotFoundError(
                    f"Parent directory for FP8 scale save path not found: {save_parent}"
                )
        return self

    @staticmethod
    def fold_mm_processor_device(
        mm_processor_kwargs: dict[str, Any] | None,
        mm_processor_device: MMProcessorDevice | None,
    ) -> dict[str, Any] | None:
        """Fold the `mm_processor_device` convenience flag into the kwargs.

        The flag keeps no state of its own: `mm_processor_kwargs["device"]` is
        the only representation of where the processor runs, so an explicit
        `device` there always wins and `"auto"` stays unresolved for

View on GitHub (pinned to c794754062)

Solutions

  1. Check the file exists at the exact path the vLLM process sees: ls -l <path> from the same container/host and cwd.
  2. Use an absolute path for the scale file, and expand ~ or env vars in the shell before passing it.
  3. If the file was never produced, first run the calibration pass with --mm-encoder-fp8-scale-save-path to create it.

Example fix

# before (file at /data/out.pt, but cwd differs)
vllm serve model --mm-encoder-attn-dtype fp8 --mm-encoder-fp8-scale-path scales.pt

# after
vllm serve model --mm-encoder-attn-dtype fp8 --mm-encoder-fp8-scale-path /data/out.pt
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def check_scale_file(p: str | None) -> None:
    if p is not None and not Path(p).is_file():
        raise SystemExit(f"FP8 scale file missing: {p}; run calibration first or fix the path")

Try / catch

try:
    MultiModalConfig(mm_encoder_attn_dtype="fp8", mm_encoder_fp8_scale_path=p)
except FileNotFoundError as e:
    raise SystemExit(f"Config rejected: {e}") from None

Prevention

When it happens

Trigger: Setting --mm-encoder-fp8-scale-path to a missing file: wrong relative path (resolved against the server process cwd), file not yet generated by the calibration run, path only present on a different node of a multi-node deployment, or a directory instead of a file.

Common situations: Running the serve command before the calibrate command finishes; running in a container where the scale file was not mounted; typos or ~ that is not shell-expanded inside quotes.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/406d161a6cbcdcdb. Report an issue: GitHub.