Troubleshooting
On this page
Find the message or the symptom, then the fix. Messages are quoted as Uitive prints them.
uitive check
"contract.ts not found; run uitive init first": the command ran outside the application's package, or the Uitive folder is elsewhere. Run it where package.json is, or pass --contract <file>; init --dir records a folder in package.json as uitive.dir.
"uitive.dir in package.json must be a folder inside the project": every command reads and writes the Uitive folder, so it can't be absolute or reach out through ... Record a folder inside the project, such as src/uitive.
"the module exports no contract: export one made with defineApp as contract": export the contract from contract.ts, made with defineApp.
actions: "Orders.Cancel" must match /^[a-z0-9][a-z0-9.:-]*$/: action IDs, route and region IDs, and context and choice values are lowercase, with dots, colons or dashes. Surfaces, contexts and blocks are camelCase. Contracts lists every rule.
surfaces: "addnew" collides with "addNew" ignoring case: models can't be trusted with case, so IDs must differ by more than case.
Errors from the contract's module itself, such as an import that doesn't resolve: check loads the contract in Node, through the project's tsconfig paths. Aliases only the bundler knows don't resolve, so keep the contract importable on its own.
"the contract changes when read back from JSON": one of its zod schemas is outside what the JSON contract carries, such as a transform. Use the field helpers or plain objects, strings, numbers, booleans, enums, arrays and nullables.
schemas: "… optional fields", "… unions", "… bytes" or "an enum of …": a request schema is past what structured outputs accept: no optional fields, one union, 60,000 bytes and 400 enum values. Most often the contract is too large: curate it, as in Coding agents.
"bindings.ts not found; it binds …" or "export bindings with fetch and perform": the bindings must export bindings, with fetch when the contract has sources and perform when actions have effects.
"Two copies of zod: the application's … and Uitive's …": Uitive shares the application's zod. Install one zod, 4.2 or later, and let the package manager deduplicate it.
"Actions share labels, so people can't tell them apart": give each action its own label; requests find actions by label.
"Sources not found by their own labels": give those sources distinct labels, or keywords, so requests that name them find them.
Installing and loading
init warns that the project's zod is older than 4.2: upgrade zod first; Uitive's schemas need 4.2 or later.
ERR_REQUIRE_ESM, or require() of an ES module fails: the packages are ES modules with a default export condition, which Node 22.12 and later can require. Update Node, or import them.
The CLI or MCP server won't start: they need Node 22 or later.
init --packages says "install failed": installing from local tarballs, such as a build of this repository, the package manager couldn't resolve a package from them. init overrides every @plurid/uitive-* package with its tarball: in pnpm-workspace.yaml for pnpm 10 and later, which pnpm 11 requires, and in package.json otherwise. Pack all eight packages into the folder, and read the warnings init prints: an older init wrote pnpm's overrides into package.json, which pnpm 11 ignores (The "pnpm" field in package.json is no longer read).
Commands and plans
A request answers "unsupported": without a model, only plain commands work, such as hide Bold; Planning lists them. Requests in plain words need the model planner on your server.
A request answers "unavailable": the client has a model planner, but it couldn't be reached, and the request needs one. The adaptation's meta.fellBack says why, such as "server answered 401: Not allowed".
"server answered 401: Not allowed": the handler's authorize refused the request. init's template allows requests only outside production; replace it with the application's session check.
"server answered 403: Cross-site requests are refused" or "415: Send JSON": the request came from a page on another site, or wasn't sent as application/json. remotePlanner sends JSON; a fetch of your own must too.
"server answered 409: The application changed; reload the page": the client's contract isn't the server's. Deploy them together; a reload picks up the new client.
"server answered 429: Too many requests; try again in a minute": over perMinute. Behind no proxy, every request shares one budget, because clients are told apart by the right-most X-Forwarded-For entry; pass client to tell them apart another way.
"server answered 503: Planning is unavailable": the server has no key for the model's provider, or the provider rejected it; onError says which. Set ANTHROPIC_API_KEY (or run ant auth login), OPENAI_API_KEY or GEMINI_API_KEY in the server's environment, never in client code.
"server answered 502: The model couldn't make a plan": onError has the reason. When it is "The model's answer didn't follow the plan's form, even when asked again", the model couldn't keep to the schema: use a model with structured output, or a stronger one; with a local server, try structured: 'json'.
"Planning with Claude needs @anthropic-ai/sdk installed": anthropic() loads Anthropic's SDK when it first plans. Install it, or plan with another provider.
The banner says "Not changed": the request named an item already as asked, such as hiding what is hidden, so nothing changed and the status is done.
A request answers "ambiguous": the words fit several actions, listed in candidates. Use the label shown, or more of it.
A request answers "not_allowed": policy refused it, such as hiding a required item, or a change the person reverted twice. Each rejection says which rule and why.
Changes that don't appear
A planned change hasn't applied: planned changes apply only at safe moments, when a session starts after a break of 30 minutes (idleMinutes), so nothing moves while someone works. Also check:
- the autonomy: in
suggest, changes wait for the person's yes; - whether the interface is frozen;
- whether the person reverted the same change recently: it waits five sessions, and a second revert blocks it for good;
- in
mixed, a model's change waits for a plan in a later session to agree, unless the evidence is strong; the banner says how many changes will apply at the next session; - whether it would push out an item that moved in the last three sessions, or a second item from the same list: it waits for a later safe moment.
Nothing learns from use: the provider and startUitive plan once a session. With a client used without either, call client.learn() when a session starts, or client.plan() yourself; learn: false turns learning off.
A tab stops saving: another tab runs a different version of the application, as after a deploy. The older tab leaves the newer one's state alone and tells onError; reloading it picks the newer state up.
A redesign shows only as a suggestion: a redesign the person didn't ask for always waits for them to accept it, whatever the autonomy.
A list doesn't reorder in the markup: adaptMarkup orders items with CSS order, which needs a flex or grid container. The console says so once: the list "…" can't be reordered: its container isn't a flex or grid box.
Hidden items still show: check that each item has data-uitive-item with the action's ID, inside a container with data-uitive-list naming the list, and that startUitive or adaptMarkup ran with the right root for markup in a shadow root.
Actions and data
"Nothing here can ask you to confirm this": a write or a destructive action ran from a generated page with no confirmation interface. Mount <Confirmations /> in React, or <uitive-confirm> elsewhere.
"Another change is waiting for your yes": one run waits for confirmation at a time.
"Changes wait until you accept or dismiss the preview": data doesn't change while a redesign is being previewed.
"This application reads no data": a page or useQuery asked for data, but the bindings have no fetch.
A table says its result is partial: the binding couldn't do all the query asked, so Uitive finished it on the client, and there were more rows to look through than scan allows (500 by default). Declare what the endpoint can do in the source's capabilities and the binding's filters, or raise scan.