Troubleshooting

[中文]

This page lists common problems and priority checks in the current System Core implementation.

Runtime App Path Missing

When the log shows Runtime app path does not exist, check:

  • Whether LittleFS is mounted on the ESP platform.

  • Whether the Device service returned a storage filesystem that supports directories, and the internal/external layout initialized successfully.

  • Whether build-time staging copied the package to <storage-root>/apps/<manifest-id>.

  • If the same manifest id exists in both internal and external, confirm the package content in the higher-priority directory is correct; duplicates are skipped.

App Not Installed

Expected app is not installed usually means the package was not scanned or manifest parsing failed. Check:

  • Whether <storage-root>/apps/<manifest-id>/manifest.json exists.

  • Whether the manifest contains the package and runtime objects.

  • Whether runtime.type maps to a runtime backend compiled in.

Manifest Parse Failure

Common causes:

  • package.id, package.version, runtime.type, or runtime.entry is missing or not a string.

  • runtime.arguments is not a string array.

  • The runtime GUI startup flow is not written in screen_flows[] of <runtime.resource_dir>/profile.json.

  • runtime.entry or runtime.resource_dir is absolute or contains ...

GUI Root Load Failure

Check:

  • Whether the native app's get_gui_descriptor().root_kind and root are correct.

  • Whether the runtime app's profile.json descriptor exists and the JSON UI document referenced by root exists.

  • Whether the root path is relative to the app resource directory.

  • Whether the ${image.xxx} or ${font.xxx} used by the native app is provided through get_gui_descriptor().resources.

  • Whether screen_flows[] contains at least one startup flow.

View Not Found

When SystemGui returns View not found, check:

  • Whether the app has started and the GUI document is loaded.

  • Whether the path/flow id of TriggerScreenFlow or SetText belongs to the current app's GUI document.

  • Whether the view path is absolute.

  • After dynamically creating a view, whether the instance path matches the path generated by the JSON UI runtime.

Service Permission Denied

A regular runtime app calling SystemCore.StartApp or StopApp is rejected, and a regular runtime app can only request to close itself. A native app must call through AppContext::system_service() instead of simulating a runtime service call.

Resource Id Conflict

When the log shows image/font resource id already registered:

  • Check whether multiple native apps use the same resource id.

  • Check whether a single native app's get_gui_descriptor().resources returns duplicate ids.

  • The current version does not support sharing the same runtime resource id across apps.

Timer Not Firing

Check:

  • Whether the timer interval/delay is greater than 0.

  • Whether the app is still Running.

  • stop_app() auto-cancels all timers of the app.