Troubleshooting

Common issues and fixes when installing or generating with ContractSpec.

Command not found

  • Reinstall the CLI and ensure it is in your PATH.
  • Confirm Node.js 20+ or Bun 1.0+ is installed.

Specs not discovered

  • Run contractspec list to see discovered specs.
  • Verify your spec path conventions in .contractsrc.json.

Build or validate fails

  • Run contractspec validate to surface schema errors.
  • Check that generated files were not manually edited.

Diagnostics

troubleshooting-diagnostics
contractspec --version
contractspec list
contractspec validate src/contracts/mySpec.ts

Still blocked?

  • Confirm compatibility requirements for runtime and framework.
  • Re-run builds on a clean branch to isolate changes.
  • Use a new spec and minimal adapter to validate setup.
Start hereCompatibilityNext: Installation