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 WorkflowExecutionError codes on a FlankExecutionService (running executions in-process) and storage errors propagated from sirloin’s FlankStorageService. Those surfaces have been deleted along with the flank engine and proto/flank/v1; brain’s HTTP API is the only error source for workflow, execution, and contract paths. (The playground character search can still surface sirloin StripService gRPC errors.)

For the full operational checklist, see flank-runbook.