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. |
FLANK_AUTH_BYPASS_UUID, when set, short-circuits the entire check and returns the
configured UUID. This must never be set outside development. With the bypass on, no Clerk
JWT is minted (mintBrainToken() returns undefined), so brain calls are sent
unauthenticated — only usable against a local brain that accepts them. 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 operator lacks the ADMIN role brain requires for workflow operations. | 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, being retired. Flank used to surface its own gRPC
WorkflowExecutionErrorcodes on aFlankExecutionService(running executions in-process) and storage errors propagated from sirloin’sFlankStorageService. Those surfaces are superseded by brain’s HTTP API.TODO(@law): remove the retired gRPC error paths once nothing depends on them.
For the full operational checklist, see flank-runbook.