Skip to content

Debugging Constraints

Rezi constraint failures are deterministic: there are no silent fallbacks and no “best effort” coercions.

This guide is a diagnosis flow for the most common constraint/layout failures.

See also: - docs/guide/constraints.md - docs/reference/constraint-expressions.md - docs/dev/live-pty-debugging.md (frame-audit workflow)

1) Identify the error class

ConstraintSyntaxError (parse-time)

Cause: invalid DSL syntax in expr("...").

Fix: - Correct the expression string - Prefer helper constraints to avoid hand-typed syntax for common patterns

ZRUI_INVALID_CONSTRAINT (frame-time)

Common causes: - Unknown function name (typo): clmp(...) - Unknown widget ref: #sidebr.w - Ambiguous direct widget ref when ids are shared - Invalid max_sibling / sum_sibling usage

Fix: - Check the expression source in the error detail - If you intended a common pattern, replace it with a helper from docs/reference/constraints-api.md

ZRUI_CIRCULAR_CONSTRAINT (frame-time)

Cause: a cycle in dependency graph (often mutual sibling width references).

Fix: - Anchor one side of the relationship to parent.*, viewport.*, or intrinsic.* - Avoid #a → #b and #b → #a loops

ZRUI_INVALID_PROPS

Cause: prop contract violations, for example: - % size strings - responsive-map layout constraints ({ sm, md, ... }) - grid.columns: expr(...) (invalid in alpha)

Fix: - Migrate to helper constraints / expr where supported - Use multiple grids and switch with display for responsive columns

2) Narrow down the source

Practical steps:

  1. Search for expr(" usages near the failing widget
  2. Check for #id.* references and confirm the referenced ids exist in the same committed tree
  3. Confirm direct #id.* targets are unique (use max_sibling / sum_sibling for shared ids)
  4. For max_sibling / sum_sibling, confirm the matching ids are siblings under the same parent as the consumer
  5. Reduce the expression to a simpler form to isolate which term is invalid

3) Use deterministic runtime evidence (frame audit)

For hard-to-reproduce visual glitches, use the PTY + frame-audit workflow:

REZI_FRAME_AUDIT=1 REZI_FRAME_AUDIT_LOG=/tmp/rezi-frame-audit.ndjson node <your-app>
node scripts/frame-audit-report.mjs /tmp/rezi-frame-audit.ndjson --latest-pid

This helps confirm whether layout/renderer diverges across frames, and provides stage-level counters.

4) Use the dev inspector overlay (constraints instrumentation)

Rezi can surface constraint graph + resolved values in the dev inspector overlay.

Enable it by using createAppWithInspectorOverlay(...) (default toggle hotkey is ctrl+shift+i):

import { createAppWithInspectorOverlay } from "@rezi-ui/core";
import { createNodeBackend } from "@rezi-ui/node";

const app = createAppWithInspectorOverlay({
  backend: createNodeBackend(),
  initialState: { /* ... */ },
});

What you’ll see: - constraints: graph node count, hidden-by-display count, and whether the last resolution was reused / cache hit / computed. - constraints_focus: resolved constraint values for the currently focused widget id (if present in the constraint graph). - constraints_exprs: the constraint expressions that apply to that focused widget instance (truncated).

Notes: - If an id is shared by multiple widgets, the overlay reports instances=N and shows one instance. Prefer unique ids when debugging. - This instrumentation is intended for development (it adds per-frame bookkeeping and allocations).

5) Recognize common constraint bugs

  • Wrong clamp(...) argument order: Rezi uses clamp(min, value, max).
  • Assuming boolean operators exist: the DSL does not support &&/||; use if(...) or ternary.
  • Creating “invisible dependencies”: referencing a widget that is conditionally omitted via show(...) can invalidate sibling refs.