Read page as text

NIB / DOCUMENTATION

Troubleshooting and migration — NibGenUI

Read safe diagnostics before changing catalogs, bindings, or hosts.

Open interactive view

Keep the first rejected frame and its last good state

Start diagnosis with a deterministic fixture. Replay from a fresh runtime in order and stop at the first rejected result. Later failures often follow from that missing creation or data update. Keep the frame number, diagnostic code and a sanitized description of the operation. Do not dump a whole response or action context into shared logs; identifiers and paths can also contain private information.

The helper below accepts one complete JSON envelope, not an arbitrary network chunk. Call it after framing, using the same runtime and surface IDs as your view. On rejection, inspect the code and leave the current surface visible. If the view is empty, first confirm that createSurface succeeded and that the renderer’s surfaceId exactly matches it. Then check that root and its referenced children are defined.

bool applyCompleteFrame(NibRuntime runtime, String frame) {
  final result = runtime.applyJson(frame);
  if (result.accepted) return true;
  for (final diagnostic in result.diagnostics) {
    debugPrint('${diagnostic.stage}: ${diagnostic.code}');
  }
  return false;
}

Inspect the rejected frame

NibApplyResult.diagnostics contains a code, safe message, stage, and optional surface, node, path, expected type, and actual type. The runtime does not include raw untrusted values in a diagnostic. The previous valid surface stays visible after a rejected mutation.

An unknown_catalog means the exact catalog ID is missing from the runtime. unknown_component means the schema has no component of that name. invalid_pointer or binding_type points to a data path or value mismatch. Check these before changing the renderer.

APITypeDefaultBehavior
NibApplyResult.acceptedboolper operationWhether a mutation was committed.
NibDiagnostic.stageStringderived from codeBroad decode, protocol, catalog, binding, graph, capability, or lifecycle category.
NibDiagnostic.suggestedFixString?nullHint for selected known rejection codes.

Follow the symptom to its layer

For unknown_catalog, compare the exact catalog ID in createSurface with the runtime registration. For unknown_component, compare the component name and schema. For a builder fallback after an accepted custom component, register its matching trusted Flutter builder. These are three different failures: catalog selection, schema validation and visual implementation. Adding a renderer cannot repair a frame that the runtime rejected.

For an unresolved label, inspect the binding path and whether the data frame arrived. For binding_type, a value exists but has the wrong type. For an uneditable field, check whether value is a literal instead of a path binding. For an inactive action, verify the Button is reachable from root, its child is complete, its event is registered, its context paths are allowed and its guard accepts current data.

For streaming problems, distinguish JSON framing from protocol validation and HTTP failure. JSONL needs complete newline-delimited objects; SSE data: prefixes are not supported. NibJsonlAdapter handles split bytes and a final line without a newline. HTTP status errors and the hard response deadline are transport failures, while a well-delivered invalid frame yields a rejected NibApplyResult.

Replay fixture on the website is a deliberate reset, not a reconnect strategy. A real reconnect must preserve generation order and surface ownership. The protocol slice has no sequence number to reject an old frame after an ID is reused, so use a fresh session or distinct IDs at that boundary. Before changing a saved format or catalog, replay known fixtures through both versions and compare accepted state and action decisions. Do not relabel an unsupported frame to a newer version and assume compatibility.

Keep generation order

Updates before createSurface and duplicate active creates are rejected. A valid update can be applied twice and emits another change event. The protocol slice has no sequence field, so a stale update after an ID is deleted and reused cannot be recognized from that ID alone.

Use a fresh runtime or distinct IDs for a new session, and keep delivery ordered across reconnects. Do not retry consequential actions without backend deduplication.

Integrate in layers

Start with a saved v0.9.1 fixture in nib_genui_core, then render the same surface through nib_genui. Add nib_genui_http only when the host has endpoint, authorization, deadlines, and reconnect policy. The website’s scripted fixture is a local demonstration, not a live provider integration.

Do not interpret a passing three-frame smoke test as complete protocol compatibility. Keep unsupported fields and Basic components outside the advertised catalog until they have schemas, trusted builders, and tests.