trtllm-build fails because an optimization profile has a minimum dimension above its optimum

TensorRT requires min to be less than or equal to opt, and opt less than or equal to max, for every dynamic dimension in an optimization profile. The engine build aborts when TensorRT-LLM derives a profile in which some dimension violates that ordering, usually because build flags imply a minimum larger than the optimum that was set.

A build-time failure in which TensorRT-LLM rejects an optimization profile because some dynamic dimension was assigned a minimum larger than its optimum, violating the min less than or equal to opt less than or equal to max ordering TensorRT requires.

TensorRT requires every dynamic dimension to satisfy min less than or equal to opt less than or equal to max, and validates it when a profile is evaluated. TensorRT-LLM runs the same check earlier so the message is legible. The ordering is violated when build flags are set independently: opt_num_tokens defaults to max_batch_size times max_beam_width, so pinning it by hand while other flags raise the derived minimum places opt underneath min for a batched dimension such as input_ids.

• trtllm-build aborts before an engine file is produced
• The same flags built successfully against an earlier TensorRT-LLM version
• The failing dimension is not named in the default build output, so there is nothing to correct
• Removing one flag makes the build succeed without explaining which value was inconsistent

• trtllm-build invocations that set --opt_num_tokens explicitly
• Builds using --multiple_profiles, where a later profile can be invalid while profile 0 is fine
• Configurations where max_seq_len is deduced from the model config and conflicts with an explicit max_input_len
• Cross-version builds where a flag's default changed between TensorRT-LLM releases

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.

• ✓Export TLLM_LOG_LEVEL=TRACE and re-run the build; the tensor shape table printed before compilation shows the minimum, optimum and maximum for each named dimension.
• ✓Compare the explicit values passed for opt_num_tokens, max_batch_size and max_beam_width; opt_num_tokens below max_batch_size multiplied by max_beam_width is the common inconsistency.
• ✓Rebuild with --multiple_profiles removed. A build that then succeeds confirms the invalid tuple was produced by profile splitting rather than by a single flag.

[TRT-LLM] [E] Error building engine: optimization profile is invalid.
[TRT-LLM] [E] min dimension is greater than opt dimension for input_ids
[TRT-LLM] [I] input_ids | Min (1) | Opt (8) | Max (8192)

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.

Letting opt_num_tokens return to its default restores the relationship it has with max_batch_size and max_beam_width, which is what the derived minimum is computed from. Printing the profile table replaces guesswork with the specific dimension name, so the flag that needs changing is identified rather than found by removing flags one at a time.

// 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.