[docs] Add a "configuration errors" troubleshooting page
#5,766 opened on Jul 12, 2026
Repository metrics
- Stars
- (7,565 stars)
- PR merge metrics
- (Avg merge 12d 9h) (245 merged PRs in 30d)
Description
Description Megatron Core validates many interactions between tensor, pipeline, context, expert, and sequence parallelism. The resulting errors are useful individually, but users lack a central explanation of how to diagnose them. Add a short troubleshooting page covering 5-8 common validation failures already present in current code. For each:
- Show a minimal invalid configuration.
- Include the relevant error text or a stable excerpt.
- Explain the violated invariant.
- Show one corrected configuration.
Candidate topics include divisibility requirements, parallel-size relationships, virtual pipeline configuration, and incompatible precision options.
Do not document runtime CUDA/NCCL failures or performance tuning in this issue.
Acceptance criteria
- Every example is verified by a CPU-only config-construction test or existing unit test.
- Examples use current configuration field names.
- Error excerpts are specific enough to search for but do not depend on line numbers.
- The page is linked from the user guide troubleshooting section.