Work through the section that matches your symptom. Most problems trace back to ports, file permissions, database connection strings, or proxy headers.

Port already in use

Change the port with --port or MEMOS_PORT and restart the server.

Cannot write to the data directory

Ensure the data directory exists and is writable by the Memos process. You can set it with --data or MEMOS_DATA.

Database connection errors

Verify the driver and DSN:

MEMOS_DRIVER should be sqlite, mysql, or postgres.
MEMOS_DSN should use the correct DSN format for your database.

Reverse proxy issues

If you run behind a reverse proxy, make sure:

MEMOS_INSTANCE_URL matches the public URL
the proxy forwards standard headers (Host, X-Forwarded-*)

Docker starts but the app does not respond

Check:

docker logs memos
whether the host port is already occupied
whether the mounted data directory is writable

Attachments are missing after migration

Confirm which storage backend the instance uses. If attachments are stored outside the database, they must be migrated and backed up separately.

Still stuck?

Check the FAQ or search GitHub issues.

Troubleshooting