Skip to content

Troubleshoot an error in a built application

Use this when the owner of an application says something like “a customer told me the order form gives an error” or “the page is empty”. The owner usually cannot say more than that, so the work is yours: find what failed, say it in plain words, fix it, and prove the fix.

Work in this order. Each step either finds the cause or rules a layer out, so do not skip ahead to rewriting the page.

Ask only for what you cannot look up: which page or form, what the person did, what they saw, roughly when, and whether they were signed in. If the message they saw showed a reference code, ask for it: it finds their exact request in step 6. A visitor who is not signed in and a signed-in user of the application reach different access rules, so the same page can work for one and fail for the other.

2. Look at the page the way the visitor does

Section titled “2. Look at the page the way the visitor does”

Call capture_page_screenshot with the page_id or path of the published page. Besides the image, the result carries the browser’s diagnostics for that load: console errors, page errors and failed or blocked requests. A failed request there names the call that broke, which is usually enough to pick the next step. Capture viewport: "mobile" as well when the report came from a phone.

The capture is anonymous unless you pass application_session. If the report came from a signed-in user, an anonymous capture that looks fine does not clear the page.

Call render_page with published: true to read the layout that is live. The draft you edited last and the published page can differ, and the visitor only ever sees the published one.

A new model is private. A visitor who is not signed in cannot read its records or create one, and a public page that lists it shows that visitor no rows. Reading and creating are opened separately.

Call get_model and read settings.anonymous_access:

{"anonymous_access": {"read": true, "create": false}}
  • A list, table, stat or chart that is empty for visitors but full for the owner means read is off, or the signed-in user has no read rule. See Compose record access boundaries.
  • A form that refuses every anonymous submit means create is off, or the stored form’s settings.access is "authenticated".

An access change takes effect as soon as it is saved and needs no republish.

Record writes are checked against the published schema, not the draft. Call get_model once with the default view and look at draftDiffersFromPublished. If it is true, a field the page or form sends may exist only in the draft, and the write is refused as a validation error. Call publish_model, then retry.

Create the same record the visitor tried to create, with the same field names and the kind of values they would type. A refusal comes back with the status and a message naming the field:

  • 422 means the data was refused: a required field is missing, a value has the wrong type or fails a validation rule, or the field is not in the published schema. On a query, a nested filter on a field that is not in the outer fields list also answers 422.
  • 401 or 403 means access: go back to step 3.
  • 409 means a uniqueness rule or a conflicting change.

Your connection acts as the application’s builder, not as a visitor. A write that succeeds for you can still fail for a visitor on access (step 3), and a rule that reads actor.id treats the two differently.

6. List the application’s problems, then read the item’s log

Section titled “6. List the application’s problems, then read the item’s log”

Start with list_problems. It returns every failure the application recorded in the last 30 days in one list, newest first: requests the platform refused, failed rule runs, scheduled job executions, notifications, webhook deliveries and service calls. Each entry gives its kind, the time, the item that failed (itemId, itemName), its status or a one-line error, and a link to where the console shows it. It needs the audit:read scope.

Narrow it before reading further:

  • reference with the code the visitor saw returns that one request failure. See “Look up a visitor’s reference code” below.
  • model_id keeps only failures of items attached to the model in the report. Services and request failures have no model, so this filter leaves them out; list without it when the report is about an outside service or a refused submit.
  • kind keeps one source, for example rule or webhook.

Each call returns at most 200 entries. When nextCursor is set, call again with it as cursor and the same filters.

An entry is a summary. A record that saves and then “nothing happens” is a failure in the automation behind it, so read that item’s own log for the full detail, using the entry’s itemId:

What should have happened List Read
A rule ran (computed a value, blocked the save, sent something) list_rules get_rule_logs with the rule_id; a failed run has error set
An email or other notification went out list_notifications list_notification_logs
An outside service was called list_services list_service_logs
A webhook was delivered list_webhooks list_webhook_deliveries
A scheduled job ran list_jobs list_job_executions

list_audit_events shows what changed in the application and who changed it, and it records a failed rule run. get_record_audit shows every change to one record, which answers “it was saved and then it changed” or “someone deleted it”.

To test a rule without touching data, call test_rule with the rule’s condition and actions and a sample context. The answer says whether the condition matched, what the actions would produce, and lists unknown_paths for any field path the rule reads that does not exist.

Make the smallest change that removes the cause. Then repeat the step that showed the failure: capture the page again, or create the record again, and confirm the error is gone. Do not report a fix you have not re-run.

Tell the owner three things in plain words: what was wrong, what you changed, and how you checked it. Leave out status codes and tool names unless they ask.

When the platform refuses a visitor’s request on a published page, an embedded form or the records API, it records the failure and shows the visitor a short reference code with the error. Ask the owner for that code and call list_problems with reference set to it, exactly as shown. The matching entry is the request failure: when it happened, the HTTP status and the message the visitor was given. It never holds the values the visitor typed.

A reference only finds request failures, and only for 30 days. If no entry matches, check the code with the owner, then fall back to step 2 and the reproduction in step 5. If you still cannot reproduce the failure, say so, and ask for the exact values the visitor entered and the wording of the message they saw.