nimbus doctor runs a set of targeted checks on your Salesforce project and reports exactly what's wrong - with a concrete fix for each issue. Think brew doctor or gh auth status.
Eight targeted 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 exactly 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 do not block the exit - they're advisory. 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.