| name | diagnose-config |
| description | Diagnose MegaLinter .mega-linter.yml configuration issues. Use when linters aren't running as expected or configuration seems wrong. |
| allowed-tools | Read Grep Glob |
| argument-hint | [config-file-path] |
| model | sonnet |
| metadata | {"internal":true} |
Diagnose MegaLinter configuration. Read the .mega-linter.yml (or path provided in $ARGUMENTS) and check for:
- Configuration hierarchy: Env vars override
.mega-linter.yml, which overrides descriptor defaults. Both .mega-linter.yml and .megalinter.yml are recognized.
- ENABLE/DISABLE conflicts:
ENABLE_LINTERS/DISABLE_LINTERS take precedence over ENABLE/DISABLE (descriptor-level). You can't enable a linter if its descriptor is disabled.
- Filter patterns: Validate
FILTER_REGEX_INCLUDE/FILTER_REGEX_EXCLUDE regex syntax
- Linter variable naming: Must be UPPERCASE with
_ separator matching the generated name DESCRIPTOR_LINTERNAME (e.g., PYTHON_PYLINT_ARGUMENTS, not pylint_arguments)
- Flavor compatibility: If using a flavor image, verify the enabled linters exist in that flavor by checking
flavors/<flavor>/flavor.json
- EXTENDS: If using remote config inheritance via HTTPS URLs, verify they're accessible
- APPLY_FIXES: Check the fix mode is compatible with the CI system — auto-commit requires write access to the branch
- Pre/Post commands: Validate
PRE_COMMANDS and POST_COMMANDS syntax (each needs command and cwd fields, cwd is root or workspace)
- Common mistakes:
- Using lowercase linter names (must be UPPERCASE)
- Missing
_ separator in linter-specific vars
- Setting
VALIDATE_ALL_CODEBASE=true in CI (slow — usually want diff-only)
- Forgetting
{LINTER}_FILTER_REGEX_INCLUDE/EXCLUDE overrides global filters
Reference megalinter/config.py for the full resolution logic.
