Troubleshooting

Audience: preview users and support
Status: Preview

Start with the smallest failing surface. For SDK issues, run ophiolite doctor. For Workbench issues, export a diagnostics bundle before retrying destructive actions.

SDK install issues

Run:

ophiolite doctor

Use the check category and code to route the failure:

Category	Typical cause	First action
install	CLI/runtime artifact missing or mismatched	Reinstall ophiolite-sdk from the supported artifact
environment	Unsupported OS, architecture, or Python lane	Compare against system requirements
cache	Ophiolite cache cannot be created or written	Set OPHIOLITE_HOME to a writable directory
runtime	Local project/runtime smoke failed	Check temporary directory permissions and local disk state
license	Missing or invalid certificate	Run ophiolite auth status
sample_workflow	Bundled sample missing or invalid	Set OPHIOLITE_SAMPLE_LAS to a readable sample LAS file

License issues

Inspect license state:

ophiolite auth status

Import a local preview certificate:

ophiolite auth import .\license.json

For a valid preview certificate, auth status should report verification_status = verified and verification_key_source = built-in-preview-key.

If OPHIOLITE_LICENSE_FILE is set, the CLI will use that path first. Unset it if it points at a stale or invalid file.

Workbench issues

Use Help -> Export Diagnostics… or the status bar Diagnostics action.

The status bar also exposes a license indicator that opens a small details dialog with the license ID, expiry date, offline-use date, and verification source. Use this when triaging activation symptoms before reaching for the CLI; the dialog’s Export diagnostics action produces the same bundle as the Diagnostics button.

If the Workbench UI cannot open far enough to use those actions, run the headless diagnostics export from the desktop binary:

ophiolite-workbench-desktop diagnostics export --headless --output workbench-diagnostics.zip

If the Workbench opens but a workflow fails:

• keep the failed run directory
• export diagnostics before restarting
• note whether the sample project path still works
• include the last visible workflow error

If the Workbench cannot open a project or sample:

• check that the selected folder still exists
• use Try sample project or Sample to regenerate the bundled preview sample under the Workbench app-data directory
• avoid moving partial run directories until diagnostics are exported
• retry with the bundled sample path before using private data

When to reinstall

Reinstall only after capturing diagnostics if:

• OPH_DOCTOR_NATIVE_RUNTIME_FAIL appears
• the Workbench starts but cannot locate bundled runtime components
• an update or local build replaced only part of the SDK or app

Do not clear caches as a first step unless the failure is clearly a cache or permission issue.

Next: Support and Diagnostics and Known Issues