Troubleshooting
First checks
Section titled “First checks”bfast versionbfast whoami --jsonbfast apps list --jsonbfast inspect --json '<app name or ID>'Update with the installer before testing a newer API contract. Put flags before positional arguments. Record the operation ID and error body. Keep credentials out of reports.
| Result | Next check |
|---|---|
| Platform request returns 401 | Check the selected CLI profile, key expiry and revocation. |
| Management returns 403/404 | Check ownership and read/write/delete scope. |
| App request returns 401 | Use an app token, not a platform key; check login and expiry. |
| App login returns 401/403 | Check the app user, password, enabled state and verification. |
| App route returns 403 | Check current role and model/File ownership. |
| Signup cannot send mail | Check app SMTP, verified sender and delivery counters. |
| Auth returns 429 | Wait before retry. Do not weaken the operation budget. |
| File upload returns 409 | Reuse a request key only with identical user, filename and bytes. |
| File upload rejects size/capacity | Check the 2 MiB transfer bound and account charged bytes. |
| Deleted URL returns 410 | Deletion completed. Retained data does not imply a running route. |
| App is starting or stopped | Inspect lifecycle state and the accepted operation. |
| Native browser fetch fails cross-origin | Use a server client or registered app origin; wildcard CORS is not supplied. |
| SDK integer fails JSON conversion | Use the generated client’s bigint encoder and toString() for display. |
| Missing metric | Treat it as unavailable. It is not proof of zero usage. |
Lost operation response
Section titled “Lost operation response”bfast operations --json '<request ID>'bfast operations --wait '<request ID>'A lost client reply can leave accepted work running. Reuse the pending request
instead of creating a second mutation. Use --new-request only after reconciling
the earlier operation. Work actions have their own retry rules; inspect their history.
Compilation and update
Section titled “Compilation and update”Read source-position diagnostics. The language supports a checked subset; Go-shaped code can still be unsupported. Compare your source with a complete downloadable example and the feature matrix. Do not rename the DSL app or assume a schema migration during ordinary update.
Report an issue
Section titled “Report an issue”Include CLI version, app ID, operation ID, approximate UTC time, expected behavior, HTTP status and safe error text. Include the smallest source example that reproduces the problem. Exclude keys, tokens, passwords, cookies, email links and private data.