Strip Error Catalog

Strip Error Catalog

Surface-level errors operators and end users see most often. Strip is mostly a translation layer to sirloin, so most failures are either auth/authz or upstream gRPC. Codes are HTTP unless noted.

#	Symptom	Where it fires	Likely cause	First action
1	Boot panic: port cannot be empty	config.ValidateConfig (ErrEmptyPort)	STRIP_PORT unset and default warning was treated as fatal in caller	Set STRIP_PORT=:8080, redeploy.
2	Boot panic: sirloin gRPC host cannot be empty	config.ValidateConfig (ErrEmptySirloinHost)	STRIP_SIRLOIN_GRPC_HOST unset	Set host (e.g. sirloin:50051).
3	Boot panic: clerk secret key required …	ValidateConfig (ErrClerkSecretRequired)	Non-dev stage missing STRIP_CLERK_SECRET_KEY	Inject Clerk secret from secret store.
4	Boot panic: invalid stage "..."	ValidateConfig (ErrInvalidStage)	Bad STRIP_STAGE value	Use production/staging/sandbox/development.
5	302 redirect to /login on every page	AuthMiddleware.RequireAuth	Missing/expired Clerk session cookie __session	Re-authenticate; check Clerk domain cookie scope.
6	401 “invalid session” / loop on /sso-callback	Clerk verification failure	Wrong STRIP_CLERK_DOMAIN / publishable key mismatch	Verify Clerk env, ensure STRIP_STAGE matches Clerk environment.
7	403 forbidden Templ page	AuthorizationMiddleware.RequirePermission	User lacks RBAC perm (view:audit_logs, manage:roles, etc.)	Confirm role assignment in sirloin / Clerk metadata.
8	403 JSON {"error":"permission_denied"} with HX-Reswap: none	Same middleware, HTMX branch	Same as above for HTMX requests	Same. UI shows toast instead of redirect.
9	429 “Too many requests, please try again later”	Global limiter.New keyed on real client IP	Caller exceeded globalRateLimitMax per globalRateLimitWindow	Throttle caller; check getRealClientIP correctness behind proxies.
10	429 on /login only	authLimiter chain	Login brute-force or refresh storm	Rate-limit upstream; investigate X-Forwarded-For.
11	500 “Failed to fetch popular examples” / “Failed to fetch shop VIs” / “Failed to fetch user details”	sirloin gRPC Strip* RPC errored	sirloin down, network blip, or upstream panic	Check sirloin health, gRPC keepalive logs.
12	500 with empty body	recover.New middleware caught panic	Nil deref / template render error	Check stack trace in logs (EnableStackTrace: true).
13	400 “User ID is required”	HandleUserDetails and friends	Missing :id in path/form	Caller bug; verify HTMX target URL.
14	”SECURITY WARNING: Authentication bypassed via UUID” log	RequireAuth bypass branch	X-Auth-Bypass or ?auth= matched STRIP_AUTH_BYPASS_UUID	Expected only in dev; investigate immediately if logged in prod.
15	”SECURITY WARNING: Skipping authentication - development mode without Clerk” log	RequireAuth dev fallback	Stage==development and clerkService==nil	Local dev only; treat as blocker outside dev.
16	Browser shows “Forbidden” full page	renderForbiddenPage	Same as #7 for non-HTMX nav	Same triage as #7.
17	Connection refused / “transport: connection error” in logs	gRPC dial to sirloin fails	sirloin not reachable, DNS, mTLS off	Verify STRIP_SIRLOIN_GRPC_HOST, network, sirloin readiness.
18	Slow gRPC, timeouts every 30–40s	gRPC keepalive (30s/10s) tearing dead conns	Network instability, sirloin GC pause	Check sirloin metrics; tune keepalive only as last resort.
19	Static asset 404 under /assets/...	Asset bundler output missing	make build-ui skipped or asset version stale	Re-run make build-ui, redeploy.
20	CSP/MIME warnings in browser console	helmetMiddlewareForStage policy	Inline script / unbundled font violating production CSP	Bundle asset properly; do not relax CSP.
21	”Image CGI URL not set” warning at boot	config.NewConfig	STRIP_IMAGE_CGI_URL empty	Set CGI URL; thumbnails will be broken otherwise.
22	Ask Strip chat returns generic error / disabled	STRIP_OPENROUTER_API_KEY empty	OpenRouter not configured	Provision key, redeploy.
23	Shop-VI links missing on listing	STRIP_BRISKET_BASE_URL empty (warned at boot)	brisket URL unset	Set STRIP_BRISKET_BASE_URL.
24	/api/auth/mcp-token returns wrong server URL	HandleMCPToken derives the (legacy) flank MCP URL by suffix swap	STRIP_MCP_SERVER_URL doesn’t end in /foxy360/mcp	Set canonical MCP URL ending in /foxy360/mcp. The derived flank MCP surface is legacy/being retired (workflow tooling moved to brain).
25	Cookie not set on dashboard after login	__session cookie has Secure: true outside dev	Browser blocks insecure cookie over plain HTTP	Run staging/prod over HTTPS only.

Triage flow

flowchart TD
  A[User report] --> B{Boot vs Runtime?}
  B -- Boot --> C[Check ErrEmpty* / ErrInvalidStage / ErrClerkSecretRequired]
  B -- Runtime --> D{HTTP code?}
  D -- 4xx --> E[Auth/Authz first: cookie + perm]
  D -- 5xx --> F[Check sirloin gRPC health]
  E --> G[Check SECURITY WARNING logs]
  F --> H[recover stack trace in logs]