Troubleshooting

Start with the server log. Linux: journalctl --user -u mddb.service -f. macOS: ~/Library/Logs/mddb/stderr.log. Set log_level = "debug" in the [debug] section for more detail, then restart.

mddb stops at startup

mddb validates config.toml before it serves anything. The message names the key.

Message	Fix
parse …/config.toml: unknown keys: …	Correct the spelling or the section of the named key.
oauth.<provider>: client_id and client_secret must both be set or both be empty	Set the missing value, or remove both.
github.app: id and private_key_file must both be set or both be empty	Set the missing value, or remove both.
failed to parse GitHub App private key	Use the .pem file that GitHub generated, unchanged.
voice-gateway.signing_private_key_pem is required for scoped tokens	Generate the key, or use token_mode = "oauth". See Voice.
… requires HTTPS except on loopback	Use HTTPS origins for server.base_url and voice-gateway.url.
available voice choices: …	Set a provider key for at least one choice, or remove unavailable choices.

The service cannot bind its port

The Linux unit allows only TCP port 8080 and ephemeral ports. After you change server.http or set a fixed webrtc_udp_port, add a SocketBindAllow drop-in. The same applies to a data_dir outside ~/mddb/data, with ReadWritePaths.

A sign-in button is missing

mddb hides a provider until config.toml has both its client ID and client secret. Restart after you add them.

Provider sign-in fails

• Redirect URI mismatch: the provider's redirect URI must equal <base_url>/api/v1/auth/oauth/<provider>/callback. Check server.base_url.
• EMAIL_NOT_VERIFIED: the provider reported no verified email. For Microsoft, add the email and xms_edov optional claims. Otherwise, sign in another way and link the provider in Settings → Personal.
• "An account already claims this email": a password account holds the address without verifying it. Verify that account's email, or change it, then retry.
• Sign-in inside the Android shell: use Sign in with another device.

Every client shares one rate limit

mddb sees the proxy's address for every request. Set trusted_proxies to the proxy's address prefixes.

Email does not arrive

• The log shows SMTP configured at startup when SMTP is set. Restart after you save SMTP settings.
• The SMTP server must offer STARTTLS. Use port 587, not 465.
• The log records each failed send with its reason.

See Email.

Git sync reports an error or a conflict

The Git Sync tab shows the last error. Conflict means the remote changed the same content. Resolve it in the repository, then pull again.

For the GitHub App:

• GitHub must reach <base_url>/api/v1/webhooks/github over HTTPS. The app's Recent Deliveries page on GitHub shows each attempt.
• A 401 Invalid signature response means github.app.webhook_secret differs from the app's webhook secret.
• The app needs Contents read and write permission and the Push event.

The voice bar does not appear

• Check that voice-gateway.mode is embedded or external.
• Open <base_url>/.well-known/gomode.json. webShell.voiceGateway.url must not be empty.
• Forward /.well-known/ through your reverse proxy.

Voice connects without audio

WebRTC audio needs UDP between the browser and the gateway. Open the UDP port in every firewall on the path, or set a fixed webrtc_udp_port and open it. A working page does not prove that UDP passes.

A voice session limit reached error means that the session limits are full. End another session or wait.

For phone-side voice problems, see Go Mode troubleshooting.