Troubleshooting
Common problems and how to resolve them. If your issue isn't here, see the GitHub repository to open an issue.
Sign-in & access
Can't sign in. Workspace owners sign in with GitHub OAuth (it needs repository access). Invited members use Google OAuth or a magic link. Magic-link requests are rate-limited to 5 per minute — wait a moment and retry. If a magic link has expired, request a fresh one.
Logged out unexpectedly. Sessions auto-refresh shortly before they expire. If you're signed out anyway, just sign in again — your work is in Git, not the session.
Connecting a repository
"Connect Repository" opens a plan picker. The Free tier is a structural signup shell — it can't create projects. Start a 14-day Starter or Pro trial to unlock the platform.
GitHub App not installed. Connecting a repo requires the Contentrain GitHub App installed on the workspace's GitHub account or organization. Install it from the connect flow or Workspace Settings → GitHub.
Repository shows as inaccessible. The GitHub App was uninstalled, suspended, or had its repository access/permissions changed. Re-grant access (or reinstall the App) and reconnect the project.
AI chat
Agent won't respond / "no API key". On Starter, the agent runs on Contentrain's Studio-hosted key (Haiku tier). On Pro, you can also bring your own Anthropic key (BYOA). A self-hosted Community deployment must provide its own NUXT_ANTHROPIC_API_KEY.
"Monthly AI messages exhausted". You've reached your plan's AI-message quota. Enable overage (Pro+) or upgrade your plan.
A model isn't selectable. The AI model tier is plan-gated — Starter = Haiku, Pro = Sonnet, Enterprise = custom.
Content & review
My changes don't show up on the content branch. Under the review workflow, agent and MCP writes land as cr/* pending-review branches. Approve them under Pending Changes. Under auto-merge, they land automatically. See Branches & Review.
"Too many open branches". Branch health warns at 50 and blocks at 80 open cr/* branches. Merge or reject pending branches; merged branches are cleaned up automatically.
Validation errors when saving. Content must satisfy the model's field definitions (required fields, types, constraints). Fix the flagged fields and save again.
CDN
Content isn't served / 401. CDN delivery is an Enterprise-Edition feature (Starter+). You need a CDN API key (crn_live_...) and at least one successful build. Trigger a build and confirm it completed. See CDN.
Forms
Submission rejected. Confirm the target model is form-enabled, the CAPTCHA (Turnstile) passed, and you're within your plan's monthly submission quota. See Forms.
MCP Cloud
429 Too Many Requests. You hit the key's per-minute rate limit or the monthly call quota. Back off for the Retry-After window, or raise the key's limits / upgrade the plan.
A tool returns a capability error. Lifecycle tools (contentrain_merge, contentrain_branch_*, contentrain_submit, contentrain_init, contentrain_scaffold, contentrain_bulk, contentrain_doctor, contentrain_scan, contentrain_apply, and contentrain_validate with fix) are not exposed over MCP Cloud — that merge/review lifecycle is Studio-owned. See MCP Cloud.
Billing
Workspace is locked. The trial expired, or a payment failed and the grace period ended. Upgrade or update your payment method in Workspace Settings → Billing. Studio never deletes your content when a subscription lapses.
Self-hosting
For deployment-level issues (database, GitHub App, session secret, providers), see Self-Hosting and Environment Variables.
Next Steps
- Core Concepts — how the pieces fit together
- Billing & Plans — limits, overage, and locked states
- Branches & Review — the content review workflow