Troubleshooting

Start with zrn doctor. Every zrn error names the file or value and a fix. The errors quoted here were produced for real.

"id ... is not valid"

zrn: error: .../zrnapp.toml: id 'badid' is not valid
zrn: fix: use reverse-DNS with at least three parts (io.github.you.app) or zrn-name for Zerone Laboratories' apps

Use something like io.github.you.notes. Do not use zrn-, which is reserved for Zerone Laboratories.

"the app did not draw"

zrn: error: the app did not draw .../x.png (exit 0)
zrnui: no page "nope" (the app has 1 pages: 0="Notes")
zrn: fix: the app must call zui_run()/app.run() with its first page; offscreen drawing needs Mesa's EGL (surfaceless) or a /dev/dri render node

Read the middle line. It lists the pages that exist. The "fix" line is generic, and here the cause is the wrong --page. Otherwise check that your program reaches run, and that zrn doctor shows "offscreen GPU".

"not in a git repository"

zrn: error: .../notes is not in a git repository
zrn: fix: the store builds from a public git repository: push the app to one first

zrn submit needs a repository, a clean HEAD and a pushed commit.

zrn verify exits 2

The package is sound but no key you trust signed it. Trust the signer in ~/.config/zrn/trusted-keys, or pass --key FILE. Exit 1 means broken: rebuild it. The same check stops zrn install and zrn-exec.

A Rust project will not build elsewhere

zrn new --lang rust writes an absolute path to your SDK copy in Cargo.toml. If you move the SDK or share the project, change that path. How the store's CI handles it is decided by its build tooling, so test a clean checkout.

The render looks different from the window

ZUI_STYLE, ZTRF_SHELL_STYLE and style = in your ~/.config/ztmetro/config decide the style, whatever your code does. --style overrides them for a run.
Moving dots are drawn at whichever instant the render happens, so two renders of them differ.
Without Segoe UI on your computer, renders use Selawik. Without Segoe MDL2 Assets, icons are the stroke versions.

My icon does not appear

Check the name against the twenty-one that exist: an unknown name draws nothing. If an icon looks like thin lines in Metro, your system lacks Segoe MDL2 Assets.

A callback did nothing, or the app froze

Everything runs on one thread. Do long work on another and come back through post.
Python: an exception in a callback prints a traceback and goes no further. Look at the terminal or ~/.local/state/zrn/<id>.log.
Rust: a closure that outlives its App will not compile, by design.

The older SDK

ztos-sdk doctor --fix installs what the phone needs for that SDK, over SSH to alarm@172.16.42.1. A package with compiled code cannot be bundled there: install it on the phone with pacman.

Checked against zrn-sdk commit ea16771. Pictures are real renders of code that compiled. Source and proof.