Skip to main content

Troubleshooting

Unknown ruleset or rule​

Cause: A name in rules.extends, include, exclude, or override does not exist.

Fix: Check spelling. Generate valid built-in IDs with Docker lint get-rules command from Built-in Rules.

Remember:

  • profile-level extends names profiles;
  • rules.extends names built-in rulesets.

Built-in rule must not be declared in root rules inventory​

Cause: A built-in rule ID was copied under top-level rules.

Fix: Remove that definition. Tune built-in rules under profiles.<name>.rules.override.

Referenced file cannot be resolved​

Relative target paths resolve from working directory first, then from config directory. Mount or check out every referenced OpenAPI file and keep relative $ref paths intact.

Unknown node type or unsupported assertion​

Cause: Custom rule uses a node type or assertion unavailable to selected OpenAPI version.

Fix: Check custom-rule assertions and node types, then rerun lint command.

Invalid rule configuration​

Specmatic rejects invalid rule IDs, unknown rule categories, unsupported custom assertions, and invalid rule settings. Read complete error output; it identifies invalid field or reference.

For configuration discovery, profile selection, repository access, reports, and exit codes, see shared Linter Troubleshooting.