Troubleshooting

When an app misbehaves under rnx, 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

rnx version

Prints the CLI version and the active engine runtime version, and tells you when either has a newer release:

rnx v0.1.172 · public beta
installed runtime v0.1.494 · stable
  ↑ CLI v0.1.176 available; run `rnx upgrade`
  ↑ default runtime v0.1.498 available; run `rnx 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:

rnx 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. A running daemon checks for new runtimes on startup and hourly and hot-swaps automatically, so you often get a fix without doing anything. Successful interactive commands also refresh a cached CLI release check in the background. When the cache finds a newer CLI, rnx prints one short stderr notice without delaying the command or changing stdout. It stays silent for agents, CI, JSON, piped, and noninteractive use; set RNX_UPDATE_CHECK=off to disable it. rnx upgrade updates both parts now.

To update only the runtime:

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

#Select a repo runtime or inspect installed runtimes

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

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

// rnx.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.

rnx 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

rnx get diagnosis    # composed read for "what just went wrong?"
rnx 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:

rnx 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