nimbus doctor runs a set of checks on your Salesforce project and reports what is wrong, with a fix for each issue. It works like brew doctor or gh auth status.
Eight diagnostics run in order. Each one reports pass, warning, or failure with a ready-to-run fix.
| Check | Validates | Severity |
|---|---|---|
| nimbus.properties found | Project configuration file exists in the project root | fail |
| Schema files found | SObject schemas have been synced from an org into .nimbus/schemas/ | warn |
| Stubs directory exists | A stubs/ directory is present for managed package and external dependency stubs | warn |
| Database connectivity | Embedded PostgreSQL can start and accept connections | fail |
| License status | Current license tier (Free / Pro / Team) and expiry date if applicable | warn |
| Apex test classes found | @isTest classes exist under the project source directories | fail |
| Config syntax | All keys in nimbus.properties are recognized - unknown keys reported | warn |
Clean project, one unknown config key.
Gate your pipeline on a clean setup before running tests. If nimbus doctor exits 1, the test run never starts, and the failure message tells the developer what to fix.
# In your CI pipeline - fail fast with a clear error
nimbus doctor && nimbus test0 when all checks pass or warn. 1 when any check fails. Warnings are advisory and do not affect the exit code. Only hard failures (missing config, no test files, broken database) cause a non-zero exit.- name: Verify setup
run: nimbus doctor
- name: Run tests
run: nimbus test --coverage --coverage-report coverage.xmlMost first-run failures fall into one of these categories.
nimbus config init from your project root (the directory containing sfdx-project.json) to generate a starter configuration file.nimbus sync -o <org>. If you don't have org access in your environment (e.g. CI), commit the .nimbus/schemas/ directory to source control after syncing locally.nimbus db reset to stop any running process and reinitialize the data directory. If that doesn't help, run nimbus reset for a full clean slate..cls files under your project for the @isTest annotation. Make sure your test classes are inside the package directories listed in sfdx-project.json and aren't excluded by a nimbus.test.exclude pattern.nimbus config properties to list every supported key. Profile-prefixed variants like %ci.nimbus.test.parallel are valid - only the base key is checked. Typos and removed keys from older versions of Nimbus are the most common cause.