Documentation menu

Troubleshooting

Locate the last completed lifecycle milestone before changing code or deployment settings.

Use a minimal known application and collect logs from both the client and daemon to establish how far its update progressed. Then follow the lifecycle from connection setup through retained acceptance, GPU submission, and display activation. The last confirmed milestone usually identifies the boundary worth investigating next.

The Daemon Cannot Start

Check builder artifacts and target libraries first. Confirm that DRM and render nodes exist, permissions permit access, the requested mode is admitted, and the Vulkan driver supports the selected presentation path.

When forcing HERA_PRESENT_MODE=zero, inspect missing-extension errors. A CPU-copy experiment can help isolate storage-sharing support, but it does not repair an unsupported output mode or unavailable display device.

The Client Cannot Create a Surface

If surface creation fails, begin with the socket path and hello version, then inspect startup deadlines and any generic server errors. A failed handshake leaves no valid session for scene updates, so resolve it before continuing to send application messages.

For rn_host, check that the bundle exists and that --component matches AppRegistry.registerComponent. Verify that the native library and headers were built together.

A Scene Is Rejected

A CommitRejected response identifies the surface and commit whose candidate failed admission. Use that correlation to inspect ownership, structural operations, finite geometry, collection bounds, and buffer references in the rejected update. Keep the earlier accepted baseline while correcting the candidate so the next diff does not depend on unpublished state.

Kit model writes remain in the model after rejection. Rejection therefore does not imply that the next body evaluation will reproduce the previous accepted description.

Commits Are Accepted but Nothing Appears

Once retained acceptance is confirmed, look for the corresponding submission progress through CommitAck. Resource pressure or renderer errors can delay that step even though the composer has published the scene. This narrows the investigation to frame preparation and renderer progression before turning to physical display activation.

If submission succeeds, investigate GPU dependencies and identified KMS activation. A signaled GPU fence or readable display descriptor is not by itself confirmation that the intended scene became active.

Text Is Missing or Incorrect

Check the font manifest, relative asset paths, fallback font, and exact font bytes in every shaping and rendering process. A valid glyph ID from a different face can produce the wrong outline without a protocol decode error.

For missing bold, verify registered family/weight faces. The system uses actual registered faces rather than synthetic emboldening.

Layout or Input Looks Stale

When the layout differs from the intended result, inspect the accepted geometry and the proposals that produced it. Fill needs a finite offer, scrolling needs a bounded viewport, and reordered stateful children need stable keys. Looking only at the newest candidate can hide the fact that the server is still using an earlier accepted description.

For targeting, preserve surface-local versus target-local coordinates and retained commit provenance. Check focus loss and cancellation before diagnosing a control as merely missing a pointer-up event.

Native Mounting Stops

For a stalled native mount, enable --trace-mount and correlate surface and commit IDs with retained outcome deadlines. A rejection leaves confirmed state in place until newer desired work or a resize permits a rebuild. A missing outcome or transport error instead makes the baseline ambiguous and terminates progression; it cannot be interpreted as a successful scene transition.

Run verification after correcting the underlying boundary, then test the representative application on the actual presentation backend when display behavior is involved.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/app/mod.rs
  • crates/server/src/frame/driver.rs
  • crates/renderer/src/present/history.rs
  • react-native/rn_host/src/fabric/mounting/mount_sink.cpp