Troubleshooting

The process will not start

Check the logs, the selected port, directory ownership and database connectivity. Native and container ports differ by default. A malformed /etc/secrets resource can prevent startup, as can a failed migration. Do not delete the database or force its schema version to make the error disappear. Preserve a copy before investigating.

Pages work but an action fails

For sign-in, check the external origin, HTTPS, cookies and provider callback configuration. For uploads, check application and proxy size limits plus storage credentials. For missing notes, clear filters and check account, space and archive state. For an unavailable error, inspect database capacity and retry only when safe.

An integration fails

Confirm the request targets the application origin rather than the landing website. Check token expiry/revocation and the operation's resource names. Webhook receivers must return valid JSON with an acceptable response, not only an empty success status. MCP clients must support Streamable HTTP and discover this server's actual tools.

A useful report

Include the source/build version, deployment method, timestamp, redacted error, steps to reproduce and expected result. Remove tokens, cookies, database strings, provider keys and private note content. Say whether the failure reproduces locally or only through the proxy. A browser screenshot alone may miss a server-side error.

A concrete first diagnostic pass

For the default local Docker setup, collect state, recent logs and a direct health response before changing configuration. An exited container needs its startup log; a running container with connection refused needs port/bind inspection; a healthy direct endpoint with a failing public endpoint points you toward the proxy path. Logs may contain user-controlled text, so redact before sharing. Do not paste a full docker inspect dump because its environment can include secrets.

docker inspect memos --format 'status={{.State.Status}} exit={{.State.ExitCode}}'
docker port memos
docker logs --since 10m --tail 100 memos
curl --verbose --max-time 10 http://127.0.0.1:5230/healthz

Use the error to choose the next test

Test only the failing layer and preserve the original data. For API errors, read both HTTP status and the returned structured error; a 404 can also hide an inaccessible resource. Record a redacted error rather than turning off access checks.