Troubleshooting

When an app misbehaves under SootSim, the first questions are always “what am I running?” and “is there a newer build that fixes it?”. These commands answer both, and surface what just happened inside the running sim.

#Check what you’re running

sootsim version

Prints the CLI version and the active engine runtime version, and tells you when a newer runtime is available:

sootsim v0.1.172 · public beta
installed runtime v0.1.494 · stable
  ↑ runtime v0.1.498 available — run `sootsim upgrade`

The CLI and the engine runtime are versioned separately. Most fixes ship in the runtime, which updates independently of the CLI.

#Get the latest after a fix lands

If you reported an issue and were told it’s fixed in a newer runtime, pull it:

sootsim upgrade

This updates the CLI only when a newer CLI exists and downloads, installs, and activates the latest engine runtime from the CDN. It ends by printing the runtime release notes in the terminal. sootsim update is an alias. A running daemon also checks for new runtimes on startup and hourly and hot-swaps automatically, so you often get a fix without doing anything. sootsim upgrade forces it now.

To update only the runtime:

sootsim runtime install            # latest on the default (stable) channel
sootsim runtime install 0.1.498    # a specific version
sootsim runtime install --channel beta

#Select a repo runtime or inspect installed runtimes

sootsim runtime list     # every runtime installed under ~/.sootsim/runtimes/
sootsim runtime which    # the active one
sootsim runtime use 0.1.494   # temporarily switch the machine default
sootsim runtime notes    # what changed / what a version fixes

To keep one app on a version, add an optional repo config:

// sootsim.config.ts
export default { runtimeVersion: '0.1.494' }

This does not change the runtime used by other repos. Remove the field to follow the current stable runtime again.

sootsim runtime notes is where “fixed in runtime X” information lives. Check it when you’re verifying a reported issue is resolved.

#See what just went wrong

sootsim get diagnosis    # composed read for "what just went wrong?"
sootsim what-happened    # recent semantic events: toasts, keyboards, screens,
                         # alerts, fetches, errors

These read the live sim’s recent semantic events, so you can see the error, alert, or failed fetch that preceded the symptom without digging through raw logs.

#Still stuck?

If an app does not render correctly and it is not a version/runtime issue, it is a compatibility gap. Scan the project’s dependencies and report it:

sootsim compat     # classify each dependency's support level

Then send a report from inside the sim; see Reporting Issues for exactly what gets captured and how a fix reaches you.

#Related

• Reporting Issues
• Wrapping an Existing App
• Compat overview