Troubleshooting
The failures that come up most, and what is actually causing each one. If none of these fit, write to us with the run id and we will look at the run itself.
Widgets
My widget is cut off, or the wrong size.
It is not built for one of the three exact sizes, or it uses responsive classes that stretch it. The grid row is a fixed 170px track and will not grow. Build for 170 × 170, 360 × 170 or 360 × 360 and wrap it in
WidgetContainer.My widget is empty on the dashboard.
The dashboard polls
GET /api/widget. Either that endpoint is not returning data, or its shape has drifted from what your Widget.tsx expects. Call it directly and compare the JSON against the component.Text is too small, or buttons are hard to tap.
Text has a 12px floor and tap targets a 44 × 44 floor, and both are checked by the gates. Use
widgetText and WidgetButton, which hold the floors for you.Automations
It never runs.
Most likely nothing is set up to start it. An automation needs a schedule, a webhook or an MCP key, and with none of them it sits there. Its page says so now. The other cause is a missing account: an automation whose integrations are not all connected is deliberately not scheduled, rather than scheduled and failing every morning.
A run is stuck on “unknown”.
Unknown means Claritty stopped watching, not that the run failed. It waits up to 55 seconds for a result while a run is allowed up to 5 minutes. The page reconciles once the run reports in. If it is still unknown much later, the run really did not report.
It only handled some of the list.
A step that fans out with
forEach stops at maxIterations, which defaults to 50 and caps at 1000. The run reports the truncation, so check the run record. Raise the cap deliberately rather than by reflex: the default exists so one long list cannot turn into a thousand emails.It sent something before I approved it.
Approval was switched off for that automation. Any automation that writes has asking on by default, and Claritty turns it back on by itself if one gains a write later. Check the setting on its page. To stop a live automation right now, disable its trigger.
“Request failed with status code 404” when I run it.
The automation is pointing at an app runtime that is no longer there, usually after a redeploy. Redeploy the automation from its page so it picks up the current runtime.
Building and deploying
My deploy was refused.
Run
claritty deploy --dry-run to see which gate failed without shipping anything. The usual answer is tenancy: a query that does not filter by the current user. The manifest is the second: something declared in intelligence.yaml that does not exist, or an agent calling a tool it was never given.The model call raises a TypeError.
get_llm_client() takes a required model id, and chat() takes a list of message dicts rather than a string. See the example in Build the code.The AI step fails sometimes.
Give the agent a deterministic fallback so the app still does something sensible when the model is busy or unavailable. Generated apps ship with one; agents added by hand often do not.
Teams
The team keeps making the same mistake.
Tell it in the room. Feedback is kept as a standing directive and applied to later work, which is the intended way to correct a team. Rewriting its instructions from scratch loses everything else it has learned.
It is slow and expensive for a simple job.
It is probably the wrong shape. A team re-decides its approach every run, which is what you want only when requests differ. If the steps are always the same, build an automation instead.
Still stuck? Email dev@claritty.ai with the automation or app id and the run id.