Everything here was met while writing the C ABI reference and the Getting started page, or was provoked on purpose to capture the exact message. Messages are quoted as the runtime printed them. Each ends with [aster error <code>: <help link>]; the code is the stable part.
Setting up
cargo: command not found
There is no Rust toolchain on your PATH. This was the first thing that went wrong on the machine used for these pages. Install Rust with rustup, open a new shell, and check cargo --version. The commands in these docs were run with Rust 1.98.0; the workspaces use edition 2024, so an old toolchain will refuse to build them.
The first build is slow, or fails offline
The first native build prints Updating crates.io index and downloads every dependency; on a busy shared machine the runtime built in about a minute and a half, and the example builds that followed took about 20 seconds. If the machine has no network, the build fails while fetching crates: use a prepared cargo cache or a complete SDK checkout. Keep Cargo.lock and pass --locked, so you build exactly the dependency set that was tested.
aster doctor says gpu: auto (cpu): no adapter: No suitable graphics adapter found
Not an error. It means no GPU driver could be loaded (typical in a container, over SSH or on a server). Windows then draw on the CPU, and headless output (aster shot, aster_app_shot, aster_app_pixels) always uses the CPU renderer anyway, so pictures are identical either way. To force a mode, put "gpu":"off" (or "on") in the app descriptor, or set ASTER_GPU.
Opening a window
neither WAYLAND_DISPLAY nor WAYLAND_SOCKET nor DISPLAY is set (code no-display)
aster_app_run (or aster run, or an example without --headless) was started where there is no desktop session. Run it from a graphical session, or use the headless paths: aster shot, the examples' --headless flag, aster_app_shot.
A failed aster_app_run uses the app up. After it failed, a second aster_app_run gave the app has already run [aster error already-ran], and aster_app_state gave the app has already run and closed. Free the app and create a new one to try again.
Driving an app headless
no interactive target ... (code click-target-missing)
The full message:
no interactive target `Nonexistent`: nothing in the last frame has that id or label; check the spelling against `tree().dump()` / `target_ids()`. A target needs `.id(..)` plus `.on_click(..)` or `.focusable()`aster_app_click and aster_app_focus look the name up among interactive elements. Print the tree (aster tree app.json, aster_app_tree) and copy the label or id from it. In Rust, an element needs an .id(..) and either .on_click(..) or .focusable() before it is a target.
My view has a typo in a node type and nothing failed
An unknown node type is not an error. It draws a placeholder and the call that set it returns 0:
#text-1 Text label="[aster: unknown type \"nonesuch\" · aster error unknown-type]"Look for unknown type in aster_app_tree or in a screenshot. The node types are listed in the runtime's docs/view-*.md files.
aster_app_type returned 0 but nothing was typed
With nothing focused, typing is accepted and ignored. Click the input first, or call aster_app_focus(app, "name").
unknown key chord "ctrl+nope", or f5 / page_down fail
aster_app_key accepts a limited set of chords. These worked: enter, ctrl+s, shift+tab, a, escape, tab, space, up, ctrl+shift+z, cmd+s (chords are case-insensitive). f5 and page_down were rejected.
unknown pointer kind 99 (0 move, 1 down, 2 up, 3 leave, 4 click)
Use the ASTER_POINTER_* constants from aster.h.
resize wants 64..16384 logical px each and a scale of 0.25..8, got 1x1 @ 1
aster_app_resize validates its arguments and changes nothing when they are out of range. The same limits clamp width, height and scale in the app descriptor: a 10x10 request gives a 64x64 frame.
the buffer holds 345599 bytes; this frame needs 345600 (360x240x4)
aster_app_pixels needs width * height * 4 bytes in device pixels (logical size times scale). Call it once with rgba = NULL to learn the size, allocate, then call again.
ms must be a finite number of milliseconds, 0 or more
aster_app_advance rejects negative, NaN and infinite times.
Threads and lifetimes
called off the UI thread ... only set_view, set_state and set_theme may be called from other threads (code wrong-thread)
Every aster_app_* function except the three setters must be called on the thread that created the app. aster_app_free from another thread frees nothing; the owner thread can still free the app afterwards. Hand work to the UI thread, or use the setters, which are safe from any thread and are applied on the UI thread.
aster_app_free called while a call on the app is still in progress (code wrong-time)
You freed the app from inside the event callback. It frees nothing. Set a flag in the callback and free after the call that fired it (aster_app_click, aster_app_run, ...) returns.
stale handle: this app pointer is not live (code stale-handle)
A setter was given an app that was already freed. The runtime refuses instead of touching freed memory. Stop other threads before you free the app. Note this protection covers the three setters only; do not call other functions, or free twice, with a freed pointer.
aster_last_error() shows an old message after a call that worked
Successful calls do not clear the message, and it is per thread. Check the return value of the call, and read the message on the thread that made it.
Bad input
JSON error at line 1 (byte 1): expected a "key" [aster error bad-json]
The descriptor, view or state is not valid JSON, or a state/descriptor object had the wrong shape (state must be a JSON object). The message gives the line and byte.
unknown theme "plaid" (use dark, light, mission_dark, ...) (code unknown-theme)
The message lists the valid names. Names are case-insensitive and accept - or a space in place of _.
label is NULL, app is NULL (code bad-argument)
A NULL pointer or invalid UTF-8 was passed where a string or app was required.
The web build
error[E0601]: main function not found in crate tutorial_web
Met while writing Getting started. The tutorial example exports C functions and has no main, so Cargo builds it as a program and fails, on a desktop target and on wasm32-unknown-unknown alike. Build it as a library by adding an [[example]] entry with crate-type = ["cdylib"] to web/aster-web/Cargo.toml; the exact lines are in Getting started. After that, cargo check and the release build succeed.
can't find crate for core / the wasm32-unknown-unknown target may not be installed
Not met here (the target was installed), but it is the usual failure: run rustup target add wasm32-unknown-unknown once.
A blank or garbled canvas
Not met here; from the tutorial. Read the frame pointer and length after the render call and copy immediately: the frame is replaced by the next render, and memory.buffer is replaced when wasm memory grows. The page was not opened in a browser in this pass, so a page-level failure (for example opening it over file://, which cannot fetch the module) was not exercised.
Windows
warning: aster-runtime@0.1.0: rc.exe not found (Windows SDK): building without VERSIONINFO
Seen on every cross-build from Linux. The build finishes and produces working-format binaries; the only loss is the version information block in the executable's properties. Building on Windows with the SDK installed adds it.
Cross-build prerequisites
cargo xwin needs network access the first time (it downloads the Microsoft C runtime and SDK, about 1 GB of cache) and XWIN_ACCEPT_LICENSE=1 to accept their license. Point XWIN_CACHE_DIR at a directory you keep so later builds do not download again.
Which file do I link a C program against?
aster_runtime.dll.lib, next to aster_runtime.dll in the build directory. At run time keep the DLL beside your executable. If Windows reports a missing vcruntime140.dll, install the VC++ 2015-2022 redistributable. (Not run on Windows in this pass.)