Skip to main content

Troubleshooting Guide

This guide contains solutions for common issues encountered by developers and operators in the Tower Defense project.

1. Database Connection Issues​

Symptom: Connection refused (500 Internal Server Error)​

  • Cause: The MySQL server is not running or the DATABASE_URL is incorrect.
  • Solution:
    1. Ensure your local MySQL instance is running (service mysql status).
    2. Check your .env file for the correct connection string.
    3. Verify that the database exists and the user has the necessary permissions.

Symptom: Too many connections​

  • Cause: The connection pool is saturated, or connections are not being properly closed.
  • Solution:
    1. Increase the max_connections in your MySQL configuration.
    2. Review your code for unclosed database connections.
    3. Adjust the connection pool settings in Drizzle.

2. Authentication Errors​

Symptom: INVALID_TOKEN or Session Expired​

  • Cause: AUTH_SECRET has changed, or the token has actually expired.
  • Solution:
    1. Re-authenticate via the login screen.
    2. Ensure the AUTH_SECRET in your .env is stable and has not been rotated unintentionally.
    3. Check the clock synchronization on your server instances.

Symptom: CSRF error / Forbidden​

  • Cause: Cross-Site Request Forgery protection is blocking the request.
  • Solution:
    1. Ensure the BETTER_AUTH_URL matches the frontend's origin precisely.
    2. Check if the frontend is correctly sending the necessary auth headers or cookies.

3. Build & Nx Monorepo Issues​

Symptom: Cannot find module '@tower-defense/...'​

  • Cause: The project graph is out of date, or libraries have not been built.
  • Solution:
    1. Run pnpm install to update node_modules.
    2. Run pnpm nx reset to clear the Nx cache and rebuild the project graph.
    3. Ensure the library exists in libs/ and is correctly referenced in tsconfig.base.json.

4. Email Delivery Failures​

Symptom: No emails received during development.​

  • Cause: smtp4dev is not running, or the SMTP configuration is incorrect.
  • Solution:
    1. Start smtp4dev and check its web interface at http://localhost:63384.
    2. Verify SMTP_HOST and SMTP_PORT in your .env file.
tip

Still stuck? Open a new issue in our repository or reach out to the development team on Discord/Slack.