Troubleshooting & FAQ
One-line fixes for the things that bite. On a self-hosted instance, most issues trace back to env config (see [[Self-Hosting]]).
| Symptom | Likely cause & fix |
|---|---|
| Can't stay logged in / cookie rejected | The session cookie is Secure — serve tela over HTTPS (or behind a TLS proxy). Plain http:// on a non-localhost host won't keep the cookie. |
Login says email_unverified (403) |
Email isn't confirmed — click the verification link or "Resend". Login accepts email or username. |
| No verification / reset email arrives | SMTP isn't configured (TELA_SMTP_* unset) — the link is logged, not sent. Set the SMTP env in prod. Reset requests always return 202 (no enumeration). |
| Semantic search / "ask" returns 503 | Embedder or LLM not configured. Cloud: check your monthly AI calls cap in [[Plans & limits]]. Self-host: set TELA_RAG_EMBED_URL (+ an LLM). Full-text search still works regardless. |
| "Ask" returns nothing | The space isn't indexed yet (embeddings run in the background on save). Self-host after a model change: run the reindex-all job. |
Hit quota_exceeded (402) |
A plan limit (spaces / pages / attachments / seats / AI calls). Quotas only block new growth, never reading or editing what exists. Upgrade, or self-host with an unlimited tier — see [[Plans & limits]]. |
| Lost paid features after the trial | The 30-day Plus trial (+ 1-week grace) ended and you dropped to Free. Nothing's deleted — you just can't add past Free's caps. [[Plans & limits]]. |
| WebDAV / rclone auth fails (401) | /dav/ authenticates with your PAT as the Basic-auth password (any username) — not your login password. Needs write scope to sync up. See [[Sync your vault (WebDAV)]]. |
| MCP returns 401 | The bearer PAT is missing/wrong/revoked (no cookie fallback), or an OAuth session expired. Re-issue a token or re-run Connect, and point the client at {instance}/api/mcp. See [[Agents & MCP]]. |
| MCP write tool 403s | Your PAT is read-scope — issue a write token. Scope is a ceiling. |
| OAuth "Connect" won't authorize | The instance has no OAuth configured, or your tela isn't publicly reachable. Use Claude Code or the stdio proxy with a PAT instead. [[Agents & MCP]]. |
| Public space 404s for visitors | Only the owner can publish, and it's whole-space only. Confirm visibility is set to Public — see [[Publishing & public URLs]]. |
| Custom domain won't issue a cert | On-demand TLS only fires on a direct-TLS edge; behind an external terminator that owns :443 it never triggers. See [[Custom domains]]. |
[!TIP] Still stuck, or have an idea? Send it straight to the tela team with the in-app Feedback button — the 💬 in the top bar, the Send feedback item in your account menu, or press ⌘K and run Send feedback. Pick Idea, Bug, or Other (optional), type a line, and send. It quietly attaches the page you're on so we have the context — no need to describe where you were.