TensorRT-LLM refuses a quantized checkpoint because its weight mapper does not recognise the export layout

TensorRT-LLM loads a checkpoint through a per-model weight mapper that expects tensor names and groupings in a particular layout. A quantized export written by a different tool, or by a different version of the same tool, can be entirely valid and still be rejected, because the mapper has no rule for the names it contains.

A checkpoint load failure caused by a mismatch between the tensor layout a quantized export was written in and the layout the target architecture's weight mapper was written to read, with no corruption of the file involved.

A quantized checkpoint is not one tensor per parameter. It carries packed weights alongside scales and zero points whose names and grouping are chosen by the exporting tool, and the mapper on the reading side hard-codes the arrangement it was written against. Two correct programs can therefore disagree about a correct file, and they do so most often when their versions have drifted apart.

• A checkpoint that other tools load without complaint is refused here
• The rejection names a mapper or a key rather than saying what layout was expected
• Re-exporting with different settings sometimes works, without making clear which setting mattered
• The same model in an unquantized form loads normally

• ModelOpt exports in W4A16 AWQ and neighbouring quantization schemes
• Model families whose mapper was written against one export tool's naming
• Version skew between the quantizer that wrote the checkpoint and the TensorRT-LLM that reads it
• Custom or community quantizations reusing an architecture name without matching its expected layout

Apply the following checklist to a small reproduction: each box below is a positive signal that you are looking at this exact failure rather than a sibling in the same taxonomy.

• ✓Load the checkpoint with the tool that wrote it. Success confirms the bytes are sound and the problem is the reader's expectations.
• ✓List the tensor names in the export and compare a sample against those the mapper looks for. A consistent difference in prefix or grouping identifies the mismatch.
• ✓Load the unquantized variant of the same model. Success there shows the architecture is supported and narrows the fault to the quantized layout.

[TRT-LLM] [E] qwen3_5_weight_mapper rejects ModelOpt W4A16_AWQ checkpoints
[TRT-LLM] [I] Loading weights via the architecture weight mapper

Timestamps and exact values vary across runs, but the pattern. An info-level start, an early WARN, an ERROR carrying the symptom. Is the actual fingerprint you should alert on. The Denpex platform flags this combination automatically.

Aligning the producer and the runtime removes the drift that the mapper is sensitive to, so the names it looks for are the names present. Re-exporting to a documented scheme works for the same reason from the other side. Comparing tensor names turns the disagreement into a specific, visible difference rather than a trial of settings.

// Typical pattern:
import torch.optim as optim
optimizer = optim.AdamW(model.parameters(), lr=3e-4)
scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=num_training_steps)
for step in range(num_training_steps):
    optimizer.zero_grad()
    loss = model(batch)
    loss.backward()
    optimizer.step()
    scheduler.step()

Adapt the snippet to your framework. The same pattern holds for PyTorch Lightning, Hugging Face Trainer, DeepSpeed, Megatron-LM, and vLLM training wrappers. Where the wrapper exposes a config flag (for examplelr_scheduler_type in Trainer), prefer the flag over the imperative API to keep the schedule declarative and reproducible.