Troubleshooting
Common errors you hit during install and deploy, and how to unstick yourself.
API crashes on boot: BETTER_AUTH_SECRET
Fix: set BETTER_AUTH_SECRET to 32+ random bytes. Generate with openssl rand -hex 32. The API intentionally throws instead of running with a bad default — see the env-vars reference.
CORS error in the browser
Fix: add the frontend origin to TRUSTED_ORIGINS_EXTRA. PUBLIC_URL is already in the trusted list — this var only adds extras (staging, custom preview domains).
Bridge iframe shows nothing in admin preview
Fix: pass customParent to the bridge with your admin origin. The Storyblok bridge defaults to app.storyblok.com and silently drops every postMessage from a different parent. See the Features → MCP page for the canonical plugin snippet.
Upload returns 403
OIDC login loops back to /login
Fix: make sure the redirect URI configured at the IdP is exactly PUBLIC_URL + '/api/auth/callback/<provider-id>'. Any mismatch — trailing slash, http vs https, wrong port — and the IdP redirects back without granting a session.