Gotchas: mistakes to check before you ship
Mistakes made at least once while writing the solution guides, in one list.
| Mistake | What happens | Do this instead |
|---|---|---|
An MCP client sending a Bearer token that is not a Supero JWT or an ak_ key | HTTP 401 Invalid bearer token: it does not carry a Supero domain. | Send the API key as X-API-Key (or as Bearer ak_…), or a JWT from login. |
Connector dialect postgres | POST /connectors/test-config passes, then the save fails. | Use postgresql. |
| Binding a database view live | The bind is refused at save time when the view has no usable primary key. | Expose a unique column in the view that can serve as the row identity. |
Calling AppShell.render() and also mounting your own React root in app.js | A blank page with nothing in the console. | Pick one of the two paths per app. |
Treating HTTP 200 from /services/execute as success | Refused operations look like successes. | Branch on success and read status_code from the body. |
filter_match="$user.username" or any other near miss | The owner filter is skipped and the rule fails open. | Use exactly $user.email, $user.uuid or $user.name, and test as a second user. |
Stripe amount written in minor units | A 100x overcharge: 4200 is $4,200. | amount is in major units: 42.00 is $42. |
Calling services.stripeCheckout or passing success_url from the browser | Undefined accessor, or the field is ignored. | The accessor is services.stripe.checkout, and browser arguments are camelCase (successUrl). |
| Reading a service call’s return value directly | You get the execute envelope, not the value. | Read result.output.<field>. |
Rendering AIChatPanel without isOpen | It renders nothing. | Pass isOpen. |
Event bindings written as @create:order | The binding never fires. | Qualify the schema: @create:shop:order. Only @signup stands alone. |
| Expecting regenerate to update the running app | The live app does not change. | Regenerating does not publish. Deploy again; the live URL is live-{domain}-{project}.supero.live. |
Importing email or sms without default_from_name / default_from_number | The import lands as incomplete instead of failing. | Set both when you import. |
What the platform itself does on a refused or misconfigured request is on the failure semantics page.