reference

Troubleshooting

Common problems and how to fix them.

Most Glyph issues fall into a small set of categories. Try the relevant section first; if your issue isn't here, check the GitHub issues.

Container issues

Backend container is unhealthy

Check the logs:

docker compose logs backend

Common causes:

Missing .env variable - the error mentions which one
Database not ready - wait 30 seconds after first start, the backend retries
Bad SECRET_KEY - must be at least 32 characters
Port 8000 already in use on the host (only matters in dev)

Database connection refused

sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (2003, "Can't connect to MySQL server on 'db'")

The db container hasn't finished starting. Wait for its health check to pass.
MYSQL_PASSWORD in .env doesn't match what MySQL was initialized with. If you changed it after the first run, drop the volume (volumes/mysql) and start fresh - or update the glyph user's password directly via SQL.

Frontend shows a blank page

Open the browser console:

Failed to fetch with the wrong URL → NEXT_PUBLIC_API_URL is wrong
CORS error → CORS_ORIGINS doesn't include your frontend URL
No console errors but blank → check that the frontend container is healthy

Authentication issues

OAuth redirect URI mismatch

The redirect_uri MUST match the registered callback URL for this application.

The callback URL on github.com / gitlab.com must exactly match APP_URL/api/auth/<provider>/callback. Common gotchas:

http vs https
Trailing slash
Different port
localhost vs your IP / domain

Update both: the OAuth app on the provider AND APP_URL in .env.

Should no longer happen - fixed in recent releases. The 401 interceptor was excluded for auth endpoints. If you still see this, hard-refresh the browser to drop a cached old build.

Lost admin access to a workspace

Use the database directly:

docker exec -it glyph-db mysql -u glyph -p"$MYSQL_PASSWORD" glyph

UPDATE workspace_members
SET role = 'admin'
WHERE user_id = (SELECT id FROM users WHERE email = 'you@example.com')
  AND workspace_id = '<workspace_uuid>';

Email issues

Invitations not sending

Check backend logs for SMTP/API errors:

docker compose logs backend | grep -iE 'email|smtp|resend|sendgrid|mailgun'

Common causes:

No provider configured → expected; share the link manually (see Inviting Members)
Bad API key → 401 in logs, regenerate the key on your provider
Sender domain not verified → 403 in logs, verify in your provider's dashboard
Gmail SMTP without App Password → use a Google App Password, not your regular password

Emails go to spam

Set up SPF, DKIM, and DMARC for EMAIL_FROM's domain. Each provider's docs explain the required DNS records.

Import / project issues

"Upload N files to this site?" alert when picking a folder

This is the browser's native security dialog for <input webkitdirectory>. There is no way to suppress it from JavaScript.

Solution: drag the folder onto the drop zone instead. Drag-and-drop uses a different API that doesn't trigger the dialog.

"File not found" after importing

If the file path contains brackets [, ], percent-encoding bugs in older versions caused 404s. Update to the latest release - this is fixed.

For other "file not found" cases, sync the project (top-right button) to refresh the file tree index.

Project import seems stuck

Initial sync runs in the background. For large repos, expect 1-5 minutes. Check:

docker compose logs backend | tail -50

Look for Cloning into 'data/<project_id>' and git pull output. If the clone fails (bad PAT, network issue), the project shows in the workspace but with no commits.

Cannot upload files larger than X MB

client_max_body_size in your reverse proxy is too low. Set it to at least 200M for nginx (Caddy is unlimited by default). See Reverse Proxy.

Search issues

Search returns no results

Trigger a project sync (top-right button on the project page) to reindex.
Check Meilisearch is healthy: docker compose ps.
Wipe and rebuild: see Search Engine.

Search shows wrong results from a deleted project

Project deletion removes its index. If results persist:

docker compose restart meilisearch

If still wrong, wipe volumes/meilisearch/ and resync all projects.

Performance

Slow file tree load

Large repos with tens of thousands of files are slow on first load. Glyph caches the file tree per commit - second load is fast.

If consistently slow, your MySQL or Meilisearch container may be CPU-starved. Check docker stats.

Editor lag

The Tiptap editor is fast for documents up to a few hundred KB. If you're hitting the limit, split the doc across multiple files (it's how the model is designed anyway).

Still stuck?

Open an issue on the GitHub repository with:

Glyph version (docker compose exec backend python -c "from app import __version__; print(__version__)")
Relevant logs (docker compose logs --tail 200)
Steps to reproduce
Expected vs. actual behavior

Updating

FAQ