Files
xmrchat/TROUBLESHOOTING.md
2026-03-31 14:35:42 +03:30

2.5 KiB

Troubleshooting Guide

This guide helps you resolve common issues when setting up and running XMRChat.

Emails are not sending

Emails are sent using the email added in MAIL_FROM_ADDRESS and MAIL_FROM_NAME in the .env file. If emails are not being sent from the application, follow these steps to diagnose and fix the issue:

1. Check Email Configuration in .env

First, verify that all required email environment variables are set correctly in your server/.env file:

  • MAIL_HOST - Your SMTP server hostname (e.g., smtp.gmail.com, smtp.mailgun.org)
  • MAIL_PORT - SMTP server port (commonly 587 for TLS or 465 for SSL)
  • MAIL_USERNAME - Your SMTP username/email address
  • MAIL_PASSWORD - Your SMTP password or app-specific password
  • MAIL_FROM_ADDRESS - The email address that will appear as the sender
  • MAIL_FROM_NAME - The display name for the sender

2. Password with Special Characters

Important: If your MAIL_PASSWORD contains a $ (dollar sign) character, you must wrap the entire value in quotes in your .env file. Otherwise, the $ will be interpreted as a variable reference.

Incorrect:

MAIL_PASSWORD=password$test

Correct:

MAIL_PASSWORD='password$test'

This applies to any environment variable value that contains $ characters. Always use double quotes around values containing special characters.

3. Verify Environment Variables are Loaded

Ensure your .env file is in the correct location (server/.env) and that the application is reading it properly. You can verify this by checking the application logs for any configuration errors.

4. Development vs Production Mode

Note that in development mode (NODE_ENV=development), the application uses Mailhog (a local email testing tool) instead of your configured SMTP server. Make sure NODE_ENV=production in your .env file if you want to use real email sending.

5. Test Email Sending

You can test email functionality using the built-in command:

docker compose exec -it nest npm run commander:send-email

This will attempt to send a test email and help identify any configuration issues.

Xmrchats appear after a few minutes (instead of a few seconds)

If xmrchats are appearing after a few minutes (rather than within a few seconds), lws likely needs to be restarted to sync with the node.

Fix

  • Restart monero-lws
  • Restart the node

Best practice

  • After upgrading the node, if it does not happen automatically try manually restarting LWS as well.