Skip to content
Development documentation describes unreleased changes.

Spec42 Troubleshooting ​

This guide now covers both the CLI and the VS Code extension.

Start With spec42 doctor ​

Run:

bash
spec42 doctor

Check:

  • which config file is in use
  • which standard-library path was resolved
  • whether that path is the bundled materialization, a prior on-disk install, or only a compatibility fallback
  • whether the resolved library paths actually exist
  • whether the CLI fell back to a legacy VS Code standard-library install

If you need machine-readable output:

bash
spec42 doctor --format json

CLI Validation Looks Different From The Editor ​

Run:

bash
spec42 check path/to/model-or-workspace

Common causes:

  • the CLI and the editor are resolving different library roots
  • the standard library failed to materialize from the embedded copy (see spec42 doctor)
  • a custom --stdlib-path or --library-path is missing
  • the workspace root used by the CLI is too narrow

What to do:

  1. Compare spec42 doctor with your editor setup.
  2. If needed, pass --workspace-root explicitly.
  3. Add --library-path or --stdlib-path explicitly to confirm the issue.
  4. Run spec42 doctor and confirm stdlib source is bundled (or an explicit override you expect).
  5. Re-run spec42 check ...; validation advice points at --stdlib-path / SPEC42_STDLIB_PATH if library roots are still missing.

For restricted development environments, point Spec42's user directories at writable locations:

bash
SPEC42_CONFIG_DIR=/tmp/spec42/config SPEC42_DATA_DIR=/tmp/spec42/data spec42 check path/to/model-or-workspace

No Standard Library Is Found ​

Check:

bash
spec42 stdlib status
spec42 stdlib path

What spec42 tries, in order:

  1. explicit CLI flags
  2. environment variables
  3. explicit config file
  4. default user config
  5. materialized install under the spec42 data directory (including embedded bundled)
  6. first-time materialization from the embedded standard library in the binary
  7. legacy VS Code standard-library install location

What to do:

  1. Run spec42 doctor and check resolved stdlib / stdlib source.
  2. If you use a custom checkout, pass --stdlib-path /path/to/sysml.library.
  3. If the data directory is not writable, set SPEC42_DATA_DIR to a writable cache directory.
  4. Use spec42 stdlib clear-cache only to delete materialized files (they are re-extracted on next run).
  5. Use --no-stdlib only when you intentionally want to validate without it.

Server Does Not Start In VS Code ​

Common causes:

  • spec42.serverPath points to a file that does not exist
  • the bundled server binary is missing from the extension package
  • the configured binary is not executable

What to do:

  1. Check spec42.serverPath.
  2. Use an absolute path if you are pointing at a custom build.
  3. Open SysML: Show SysML Output (Logs).
  4. Restart the server after fixing the path.

Missing Hover, Definition, Or References ​

Common causes:

  • the server is still indexing
  • the file contains invalid intermediate syntax
  • the required library roots are not included in spec42.libraryPaths

What to do:

  1. Wait until the status bar no longer shows Indexing.
  2. Check diagnostics in the current document.
  3. Validate spec42.libraryPaths and remove broken paths.
  4. Restart the server if the document was already open during a crash.

Workspace Results Are Incomplete ​

Workspace indexing uses spec42.workspace.maxFilesPerPattern.

What to do:

  1. Increase spec42.workspace.maxFilesPerPattern for larger repositories.
  2. Use smaller focused workspaces if indexing becomes too slow.

Connection And Port Semantic Warnings ​

SysML v2 allows logical part-to-part connect statements (for example connect navigation to system between part usages). Spec42 does not emit connection_endpoint_not_port when both endpoints are part-like.

Port compatibility checks apply when endpoints are ports:

  • port_type_mismatch compares port features and definitions. If two ports share a simple type name (for example FillState) but resolve to different port def elements in different packages, the message names the qualified definitions so you can align imports or reuse one port definition.
  • Conjugation and direction mismatches are reported separately when feature lists are unavailable.

Spec42 is the SysML v2 language server and tooling behind Elan8 model-based engineering.