Flank Errors
Flank is the visual workflow editor; it owns no workflow data and runs no executions. The errors a user or operator sees come from two places: flank’s own auth guard on TanStack Start server functions, and failures propagated from brain when flank calls its HTTP workflow API.
Authentication errors
Defined in apps/flank/app/lib/auth.ts. The TanStack Start server functions call
requireAuth() at the top of every handler.
| Thrown message | Cause |
|---|---|
Unauthorized: no request context | Server function invoked outside a request scope (e.g. background task). |
Unauthorized: valid Clerk session required | No or invalid Clerk session cookie/bearer. |
There is no environment-driven authentication bypass. Local development must configure Clerk and use a valid session, matching deployed behavior. See the security model.
Errors propagated from brain
Flank’s server functions call brain over HTTP via
apps/flank/app/lib/brain-http-client.ts. A non-2xx brain response is surfaced as an
error of the form brain <METHOD> <path> failed: <status> <statusText> — <body>. Common
cases:
| Symptom | Likely brain-side cause | Where to look |
|---|---|---|
brain … failed: 401 / 403 | Clerk session invalid/expired, or the caller lacks the role required by that operation. Authoring and sandbox operations require ADMIN; published discovery/execution permits CREATOR. | apps/flank/app/lib/auth.ts (token minting), brain RolesGuard. |
brain … failed: 404 | Workflow, subworkflow, or execution does not exist (bad id/name). | Confirm the id/name; brain owns the records. |
brain … failed: 400 | Invalid graph, input schema mismatch, or a save-validator violation (e.g. illegal subworkflow nesting). | Brain’s workflow save/validation; inspect the response body. |
brain … failed: 5xx | Brain internal/storage error the caller can’t remedy. | Brain logs; escalate to brain on-call. |
BRAIN_API_URL environment variable is required but not set | Flank misconfigured — no brain target. | apps/flank/app/lib/brain-http-client.ts; set BRAIN_API_URL. |
| Fetch/connection error (no status) | Brain unreachable on the configured host. | Network / brain health; verify BRAIN_API_URL. |
Authoritative error semantics for workflow validation, execution, and contracts live in brain — see brain.
Legacy, retired (removed). Flank used to surface its own gRPC
WorkflowExecutionErrorcodes on aFlankExecutionService(running executions in-process) and storage errors propagated from sirloin’sFlankStorageService. Those surfaces have been deleted along with the flank engine andproto/flank/v1; brain’s HTTP API is the only error source for workflow, execution, and contract paths. (The playground character search can still surface sirloinStripServicegRPC errors.)
For the full operational checklist, see flank-runbook.