vLLM v0.28: The Breaking Change to Check Before You Upgrade

vLLM shipped v0.28.0 on August 26, 2026: 584 commits, 270 contributors, 76 of them brand new to the project. Most of that is routine. One line in the changelog isn’t: bitsandbytes quantization support got pulled out of core and shipped as a separate plugin. If your serving stack quantizes with bitsandbytes, pip install --upgrade vllm alone will break your next restart.

What breaks when you upgrade to vLLM v0.28.0

If you run vLLM with quantization="bitsandbytes" or load_format="bitsandbytes", upgrading to v0.28.0 without an extra step breaks model loading. Bitsandbytes support moved out-of-tree into a standalone package, vllm-bnb-plugin, and vLLM’s core no longer ships it by default. Everyone else can upgrade normally.

This isn’t a case of the feature disappearing. It’s a scope decision. vLLM has been trimming quantization backends that only a subset of users touch out of the main tree, presumably so the core release cycle isn’t gated on maintaining every quantization format alongside the model-serving code most people actually depend on. Bitsandbytes is the first one out the door. Given how the release notes frame it, it probably won’t be the last.

Why bitsandbytes specifically, and not GPTQ or AWQ? It’s the quantization method most tied to a third-party library’s own release cadence rather than vLLM’s internal kernels, which makes it a natural first candidate to peel off into a plugin that can version independently.

Check whether you’re affected

Before you touch the upgrade, find out if you’re actually using bitsandbytes. Two checks, thirty seconds:

# See what version you're currently running
python -c "import vllm; print(vllm.__version__)"

# Search your launch scripts and configs for bitsandbytes usage
grep -rn "bitsandbytes\|load_format.*bitsandbytes\|quantization.*bitsandbytes" \
  configs/ deploy/ *.sh *.py 2>/dev/null

No matches, no problem — upgrade as usual. A hit means you need the plugin installed before the new vLLM binary ever tries to load a model.

If you’re running QLoRA-fine-tuned checkpoints in production, this is worth double-checking even if you don’t remember setting the flag explicitly, since bitsandbytes is the default quantization path for a lot of LoRA and QLoRA workflows that get handed off from training to serving without anyone re-reading the load config.

How to fix it

Install the plugin before upgrading, or right after, but before you restart the server that’s actually serving a bitsandbytes-quantized model:

uv pip install vllm-bnb-plugin
# or, without uv:
# pip install vllm-bnb-plugin

The plugin registers itself through vLLM’s general_plugins entry-point mechanism, so once it’s installed, quantization="bitsandbytes" and load_format="bitsandbytes" work exactly like they did before v0.28.0. Nothing in your serving code or launch flags needs to change. The only new thing is that this dependency is now explicit instead of bundled.

If you manage vLLM through a Docker image or a pinned requirements file (most production setups do), add the plugin as its own line rather than relying on it coming along for the ride with vLLM. That’s the mistake that turns a planned upgrade into a 2am incident.

The structured-output fixes are the quieter win here

The bitsandbytes change gets top billing because it breaks things loudly. The more useful change for most teams is buried further down: a batch of structured-output and request-validation fixes that make vLLM behave better when a client sends something malformed.

The one worth testing yourself: a non-object JSON body now returns a 400 instead of a raw 500.

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '"this is valid json but not an object"'

Before v0.28.0, a malformed body like that could take down the request with a generic server error, the kind that shows up in your monitoring as “vLLM is unhealthy” when the actual problem is a client bug three services upstream. Now it’s a clean 400, because a consolidated exception handler catches it at the entrypoint instead of letting it propagate as an unhandled exception. If you’re running JSON mode or tool-calling at any real scale, that distinction is the difference between one bad client request and a false-positive page at 2am.

A few related fixes landed alongside it: request stop tokens now stay masked in xgrammar until the grammar finishes, so structured generation can’t get cut short by a stop sequence that happens to match a token inside valid JSON. NUL bytes are rejected in structured_outputs.regex, negative token IDs are rejected as out-of-vocabulary instead of silently passed through, and validation failures now raise a dedicated VLLMValidationError instead of whatever generic exception happened to bubble up. None of this changes correct requests. It changes what happens to incorrect ones, which is exactly the category of bug that’s expensive to debug in production and cheap to fix at the source.

What else shipped

New model support in this release includes Ling 3.0 Flash and Meta’s Muse Glimmer, the 30B agent model built to run on a single consumer GPU, along with several multimodal and MoE additions. If you’re routing requests across more than one backend or model family, this is also a reasonable moment to check whether your routing layer’s model list needs updating to take advantage of what’s new.

A few smaller removals are worth a quick grep before you upgrade, even if none of them are as disruptive as the bitsandbytes move: the deprecated calculate_kv_scales runtime KV scale calculation is gone, override_attention_dtype was removed, and legacy MoE code was deleted. If your config touches any of those three, you’ll find out at startup, not at request time, which at least keeps the failure mode honest.

The upgrade checklist

1. Check your current version and grep for bitsandbytes usage before you do anything else.
2. If you use bitsandbytes, install vllm-bnb-plugin first, pin it in your requirements file, and only then run the vLLM upgrade.
3. If you use calculate_kv_scales or override_attention_dtype, remove them from your config; they no longer exist.
4. Re-test malformed-input handling on any endpoint doing JSON mode or tool calling. The 400-vs-500 behavior is a genuine operational improvement, but only if your error handling downstream expects it.
5. Read the full release notes for the complete diff before touching a production fleet. This piece covers what matters most; it isn’t a substitute for the changelog.

The bitsandbytes move is a five-minute fix once you know it’s coming, and a genuinely bad morning if you find out from a failed pod restart instead. Check your config before you upgrade, not after.