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.
1. Pin down the report
Section titled “1. Pin down the report”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.
3. Check access to the model
Section titled “3. Check access to the model”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
readis off, or the signed-in user has no read rule. See Compose record access boundaries. - A form that refuses every anonymous submit means
createis off, or the stored form’ssettings.accessis"authenticated".
An access change takes effect as soon as it is saved and needs no republish.
4. Check that the schema is published
Section titled “4. Check that the schema is published”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.
5. Reproduce the write yourself
Section titled “5. Reproduce the write yourself”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
fieldslist 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:
referencewith the code the visitor saw returns that one request failure. See “Look up a visitor’s reference code” below.model_idkeeps 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.kindkeeps one source, for exampleruleorwebhook.
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.
7. Fix, prove, and report
Section titled “7. Fix, prove, and report”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.
Look up a visitor’s reference code
Section titled “Look up a visitor’s reference code”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.
