NVIDIA / NVIDIA/Megatron-LM

[docs] Add a "configuration errors" troubleshooting page

Open
#5,766 1 comment 0 reactions 0 assignees View on GitHub
documentation good first issue
Dominant language
Python
Stars
17.9k
Forks
4.5k
Avg merge
4d 6h
Merged PRs (30d)
271

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.

Contributor guide

Open the contributing guide

Research direction

Start by reading the current configuration validation code and existing CPU-only config-construction or unit tests to identify 5-8 stable failures. Draft the page in the user guide troubleshooting section with invalid and corrected configurations, searchable error excerpts, and explanations of each invariant. Done means every example is verified, uses current field names, excludes runtime CUDA/NCCL and performance topics, and the page is linked from troubleshooting.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, machine-learning
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.