Skip to main content

Troubleshooting

No config file found​

Cause: Current directory contains neither specmatic-linter.yaml nor specmatic-linter.yml.

Fix: Run from the config directory or pass --config path/to/config.yaml.

Multiple profiles are available​

Cause: Config has several profiles and none is named default.

Fix: Pass --profile <name> or rename the normal profile to default.

No API description files were provided​

Cause: No target argument was supplied.

Fix: Pass one or more files:

docker run --rm \
  -v "$(pwd):/usr/src/app" \
  -w /usr/src/app \
  specmatic/enterprise \
  lint openapi.yaml

Glob does not match files​

Specmatic preserves an unmatched glob, then reports the missing target during linting. Check the path relative to the working directory and quote the pattern:

docker run --rm \
  -v "$(pwd):/usr/src/app" \
  -w /usr/src/app \
  specmatic/enterprise \
  lint "specs/**/*.yaml"

Report exists but command failed​

Expected behavior. Specmatic writes the report, then exits 1 when at least one error-level violation exists. Review report details or temporarily change adoption-stage rules to warn.

Report is not in current directory​

Reports are created relative to the linter config directory. With central Git configuration, that directory is inside .specmatic-linter/repos/. Use the exact path printed by the command.

Central config repository cannot be fetched​

Check:

  • repository URL and default branch;
  • network access from the process or container;
  • CENTRAL_CONFIG_REPO_TOKEN presence for private HTTPS repositories;
  • token read permission; and
  • repo-relative --config path.

Configuration is rejected​

Specmatic rejects unknown config keys, invalid severities, missing profiles, and circular profile inheritance. Read complete error output; it identifies invalid field or reference.

For rule, node-type, assertion, and reference failures, see OpenAPI Troubleshooting.