vllm-project/vllm · error · Exception

Unexpected level value ({args.level})

Error message

Unexpected level value ({args.level})

What it means

The layerwise profiler visualizer maps --level to a tree depth: 'module' -> -2 with unique names, 'kernel' -> -1. Any other string raises Exception('Unexpected level value (...)'). The argparse definition does not restrict choices, so typos surface only at this late check.

Source

Thrown at tools/profiler/visualize_layerwise_profile.py:616

    )
    parser.add_argument(
        "--step-plot-interval",
        type=int,
        default=4,
        help="For every `step_plot_interval` steps, plot 1 step",
    )

    args = parser.parse_args()

    # Prepare/Extract relevant args
    make_names_unique = False
    if args.level == "module":
        depth = -2
        make_names_unique = True
    elif args.level == "kernel":
        depth = -1
    else:
        raise Exception(f"Unexpected level value ({args.level})")

    output_directory = (
        args.output_directory if args.output_directory else Path(args.json_trace).parent
    )

    if not os.path.exists(output_directory):
        os.makedirs(output_directory)

    main(
        Path(args.json_trace),
        output_directory,
        depth,
        args.plot_metric,
        make_names_unique,
        args.top_k,
        args.fold_json_node,
    )

View on GitHub (pinned to c794754062)

Solutions

1. Use `--level module` or `--level kernel` exactly.
2. Check `python tools/profiler/visualize_layerwise_profile.py --help` for accepted values before running.

Example fix

# before
python tools/profiler/visualize_layerwise_profile.py --json_trace trace.json --level modules
# -> Exception: Unexpected level value (modules)

# after
python tools/profiler/visualize_layerwise_profile.py --json_trace trace.json --level module

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--level", choices=["module", "kernel"], required=True)
args = parser.parse_args()  # rejects bad values with a usage error, not a late Exception

def is_valid_level(value: str) -> bool:
    return value in {"module", "kernel"}

When it happens

Trigger: Running tools/profiler/visualize_layerwise_profile.py with `--level` set to anything other than exactly 'module' or 'kernel' (e.g. 'modules', 'op', 'Layer').

Common situations: Guessing a level name from CLI help; copy-pasting a command from an old doc/blog that used a different level vocabulary.

Related errors

• PyYAML is required. Install it with: pip install pyyaml
• Interactive input is unavailable. Pass --model and --hardwar
• No selectable items found.
• No recipe model matched {requested!r}.
• Hardware {requested!r} is not available for this model. Avai

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