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 (if a newer one exists) and downloads, installs, and activates the latest engine runtime from the CDN. 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

#Pin, roll back, or inspect runtimes

sootsim runtime list     # every runtime installed under ~/.sootsim/runtimes/
sootsim runtime which    # the active one
sootsim runtime use 0.1.494   # pin/roll back to a specific version
sootsim runtime notes    # what changed / what a version fixes

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