Spec42 Troubleshooting
This guide now covers both the CLI and the VS Code extension.
Start With spec42 doctor
Run:
bash
spec42 doctorCheck:
- 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 jsonCLI Validation Looks Different From The Editor
Run:
bash
spec42 check path/to/model-or-workspaceCommon 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-pathor--library-pathis missing - the workspace root used by the CLI is too narrow
What to do:
- Compare
spec42 doctorwith your editor setup. - If needed, pass
--workspace-rootexplicitly. - Add
--library-pathor--stdlib-pathexplicitly to confirm the issue. - Run
spec42 doctorand confirmstdlib sourceis bundled (or an explicit override you expect). - Re-run
spec42 check ...; validation advice points at--stdlib-path/SPEC42_STDLIB_PATHif 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-workspaceNo Standard Library Is Found
Check:
bash
spec42 stdlib status
spec42 stdlib pathWhat spec42 tries, in order:
- explicit CLI flags
- environment variables
- explicit config file
- default user config
- materialized install under the spec42 data directory (including embedded bundled)
- first-time materialization from the embedded standard library in the binary
- legacy VS Code standard-library install location
What to do:
- Run
spec42 doctorand checkresolved stdlib/stdlib source. - If you use a custom checkout, pass
--stdlib-path /path/to/sysml.library. - If the data directory is not writable, set
SPEC42_DATA_DIRto a writable cache directory. - Use
spec42 stdlib clear-cacheonly to delete materialized files (they are re-extracted on next run). - Use
--no-stdlibonly when you intentionally want to validate without it.
Server Does Not Start In VS Code
Common causes:
spec42.serverPathpoints 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:
- Check
spec42.serverPath. - Use an absolute path if you are pointing at a custom build.
- Open
SysML: Show SysML Output (Logs). - 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:
- Wait until the status bar no longer shows
Indexing. - Check diagnostics in the current document.
- Validate
spec42.libraryPathsand remove broken paths. - 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:
- Increase
spec42.workspace.maxFilesPerPatternfor larger repositories. - 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_mismatchcompares port features and definitions. If two ports share a simple type name (for exampleFillState) but resolve to differentport defelements 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.