vllm-project/vllm · error · ValueError

Hardware recipe JSON does not contain a usable `strategy` fi

Error message

Hardware recipe JSON does not contain a usable `strategy` field.

What it means

strategy_sources() reads the hardware recipe JSON and requires a non-empty string in its top-level 'strategy' field (the recommended serving strategy). If the field is absent, null, empty, or a non-string, this ValueError aborts before alternatives are considered.

Source

Thrown at tools/recipes/recipe_json_to_vllm_config.py:269

        )
        if selected is None:
            raise ValueError(
                f"Hardware {requested!r} is not available for this model. "
                f"Available: {', '.join(hardware_ids)}"
            )
        return selected, by_hardware[selected]

    print("\nAvailable hardware:")
    selected = choose_from_menu(hardware_ids, lambda value: value, "Select hardware: ")
    return selected, by_hardware[selected]


def strategy_sources(
    api_base: str, hardware_json_url: str, recipe: dict[str, Any]
) -> tuple[str, dict[str, str]]:
    recommended = recipe.get("strategy")
    if not isinstance(recommended, str) or not recommended:
        raise ValueError(
            "Hardware recipe JSON does not contain a usable `strategy` field."
        )

    sources = {recommended: hardware_json_url}
    raw_alternatives = recipe.get("alternatives") or {}
    if not isinstance(raw_alternatives, dict):
        raise ValueError(
            "Hardware recipe JSON `alternatives` must be an object when present."
        )

    for strategy, path in raw_alternatives.items():
        if isinstance(strategy, str) and strategy and isinstance(path, str) and path:
            sources[strategy] = api_url(api_base, path)

    return recommended, sources


def select_strategy(

View on GitHub (pinned to c794754062)

Solutions

1. Open the recipe JSON and ensure the hardware-level object contains "strategy": "<strategy-id>" as a non-empty string.
2. Regenerate or re-download the recipe from the Recipes API to get a schema-conformant file.
3. Validate the JSON structure against a known-good recipe before passing it.

Example fix

# before (recipe.json)
{ "hardware": { "h100": { "alternatives": { "...": "..." } } } }
# -> ValueError: Hardware recipe JSON does not contain a usable `strategy` field.

# after
{ "hardware": { "h100": { "strategy": "tp4-pp2", "alternatives": { "...": "..." } } } }

recommended = recipe.get("strategy")
if not isinstance(recommended, str) or not recommended:
    raise SystemExit("recipe JSON lacks a usable 'strategy' string; fix or regenerate the file")

def has_usable_strategy(recipe: dict) -> bool:
    return isinstance(recipe.get("strategy"), str) and bool(recipe["strategy"].strip())

When it happens

Trigger: Passing a hand-written or edited recipe JSON whose 'strategy' key was removed/renamed/misnested; consuming an upstream recipe file from a different (older/newer) schema version.

Common situations: Authoring custom recipe JSONs for internal models; a Recipes API format change leaving 'strategy' out of some entries.

Related errors

• Hardware recipe JSON `alternatives` must be an object when p
• Hardware {requested!r} is not available for this model. Avai
• Strategy {requested!r} is not available for this model/hardw
• No selectable items found.
• No recipe model matched {requested!r}.

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