Debugging Guide

Comprehensive guide for debugging LuaBeans - Community Manager issues.

Debug Mode

Enable debug mode in development:

NODE_ENV=development

This will:

• Show detailed error messages

• Enable verbose logging

• Disable production optimizations

Logging

Application Logs

Application logs are output to the console (stdout/stderr). In production, redirect these to log files:

node src/server.js >> /var/log/luabeans/app.log 2>&1

Log Levels

• Info: Normal operation messages

• Warn: Warning messages (non-critical issues)

• Error: Error messages (critical issues)

Common Log Messages

Startup:

[LuaBeans - Community Manager] listening on :27000 (production)

Database Connection:

[MiamiHub] DB init failed: [error details]

Discord Bot:

[LuaBeans - Community Manager Bot] ready
[LuaBeans - Community Manager Bot] rate limited: {...}

Database Debugging

Check Database Connection

mysql -u luabeans_user -p -h localhost luabeans

View Table Structure

DESCRIBE luabeans_users;
SHOW CREATE TABLE luabeans_users;

Check Table Exists

SHOW TABLES LIKE 'luabeans_%';

View Data

SELECT * FROM luabeans_users LIMIT 10;
SELECT COUNT(*) FROM luabeans_departments;

Check Indexes

SHOW INDEXES FROM luabeans_users;

View Foreign Key Constraints

SELECT 
    CONSTRAINT_NAME,
    TABLE_NAME,
    COLUMN_NAME,
    REFERENCED_TABLE_NAME,
    REFERENCED_COLUMN_NAME
FROM 
    INFORMATION_SCHEMA.KEY_COLUMN_USAGE
WHERE 
    TABLE_SCHEMA = 'luabeans' 
    AND REFERENCED_TABLE_NAME IS NOT NULL;

Common Database Issues

Connection Refused:

• Check MySQL is running: sudo systemctl status mysql

• Verify credentials in .env

• Check firewall rules

Table Doesn't Exist:

• Run schema: mysql -u user -p database < db/schema.sql

• Or let Sequelize auto-create on boot

Foreign Key Constraint Violations:

• Check referenced records exist

• Verify constraint definitions in schema

Discord Debugging

OAuth2 Issues

Error: Invalid Redirect URI

1. Verify DISCORD_CALLBACK_URL matches exactly in Discord Developer Portal

2. Check for trailing slashes

3. Verify protocol (http vs https)

Error: Not in Guild

1. Verify DISCORD_GUILD_ID is correct

2. Check user is actually in the Discord server

3. Verify bot has permissions to read members

Error: OAuth2 Application Not Found

1. Verify DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET are correct

2. Check Discord application still exists

3. Verify application hasn't been deleted

Bot Issues

Bot Not Responding:

1. Check bot is running: npm run bot

2. Verify DISCORD_BOT_TOKEN is correct

3. Check bot has required intents:

   • Guilds

   • Guild Members

   • Guild Messages

   • Message Content

Commands Not Appearing:

1. Wait 1 hour for global commands to propagate

2. Or set DISCORD_BOT_PUBLIC_COMMANDS=false for instant guild commands

3. Redeploy commands: npm run bot:deploy

Rate Limiting:

• Check logs for rate limit warnings

• Bot automatically handles rate limits with retries

• Consider reducing command frequency

Discord API Testing

Test Discord API manually:

// Test bot connection
const { Client, GatewayIntentBits } = require('discord.js');
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMembers
  ]
});

client.once('ready', () => {
  console.log('Bot connected!');
  client.destroy();
});

client.login(process.env.DISCORD_BOT_TOKEN);

Session Debugging

Check Session Store

SELECT * FROM luabeans_sessions;

Clear All Sessions

DELETE FROM luabeans_sessions;

Session Issues

Sessions Not Persisting:

• Verify session table exists

• Check SESSION_SECRET is set

• Verify database connection

Session Expired Too Quickly:

• Check session expiration settings (default: 7 days)

• Verify server time is correct (NTP sync)

CSRF Token Errors:

• Clear browser cookies

• Check TRUST_PROXY is set correctly if behind proxy

• Verify session is working

Permission Debugging

Check User Permissions

-- Get user's Discord roles
SELECT roles_json FROM luabeans_users WHERE id = ?;

-- Get user's RBAC permissions
SELECT * FROM luabeans_rbac_role_permissions 
WHERE discord_role_id IN (
  SELECT JSON_UNQUOTE(JSON_EXTRACT(roles_json, CONCAT('$[', idx, ']')))
  FROM (SELECT 0 AS idx UNION SELECT 1 UNION SELECT 2) AS indexes
) AND discord_guild_id = ?;

Check Department Access

-- User's department memberships
SELECT * FROM luabeans_department_memberships WHERE user_id = ?;

-- User's department leadership
SELECT * FROM luabeans_department_leaders WHERE user_id = ?;

-- User's department blocks
SELECT * FROM luabeans_department_member_blocks WHERE user_id = ?;

Permission Cache

Permissions are cached. To refresh:

• User: Dashboard → "Refresh roles" button

• Admin: Admin → "Refresh roles for all users" (background job)

FiveM Integration Debugging

API Token Issues

Error: Invalid Token

1. Verify LEO_API_TOKEN matches between web panel and FiveM resource

2. Check token is sent in Authorization header: Bearer <token>

3. Verify token hasn't expired or been changed

Error: Unauthorized

1. Check API endpoint is protected with LEO_API_TOKEN

2. Verify token format is correct

3. Check request includes Authorization header

FiveM Resource Issues

Resource Not Starting:

1. Check convars are set correctly:

   set LUABEANS_API_BASE "https://hub.example.com"
   set LUABEANS_LEO_API_TOKEN "your-token"

2. Verify API endpoint is accessible from FiveM server

3. Check resource console for errors

API Calls Failing:

1. Test API endpoint manually:

   curl -H "Authorization: Bearer your-token" \
        https://hub.example.com/api/leo/user/DISCORD_ID/departments

2. Check FiveM server can reach your web panel

3. Verify SSL certificate is valid (if using HTTPS)

Discord Identifier Issues

Error: No Discord Identifier

1. Verify player has discord: identifier in FiveM

2. Check player identifiers: GetPlayerIdentifiers(source)

3. Ensure Discord identifier is in format: discord:123456789012345678

File Upload Debugging

Upload Directory Issues

Error: Cannot Write to Upload Directory

1. Check UPLOAD_DIR exists: ls -la ./uploads

2. Verify write permissions: chmod 755 ./uploads

3. Check disk space: df -h

Error: File Too Large

1. Check MAX_FILE_SIZE in .env (default: 100MB)

2. Verify proxy allows upload size (Nginx: client_max_body_size)

3. Check Cloudflare upload limits

Upload Processing Issues

Uploads Not Saving:

1. Check file system permissions

2. Verify UPLOAD_DIR path is correct (absolute vs relative)

3. Check disk space availability

Performance Debugging

Slow Queries

Enable query logging in MySQL:

SET GLOBAL general_log = 'ON';
SET GLOBAL log_output = 'TABLE';

View slow queries:

SELECT * FROM mysql.slow_log ORDER BY start_time DESC LIMIT 10;

Memory Issues

Monitor Node.js memory:

# Check memory usage
node --max-old-space-size=4096 src/server.js

# Or use process monitor
pm2 monit

Database Connection Pool

Check active connections:

SHOW PROCESSLIST;
SHOW STATUS LIKE 'Threads_connected';

Network Debugging

Check Port Availability

# Check if port is in use
lsof -i :27000
netstat -tulpn | grep 27000

Test HTTP Endpoints

# Test health endpoint
curl http://localhost:27000/healthz

# Test readiness endpoint
curl http://localhost:27000/readyz

# Test with authentication
curl -H "Authorization: Bearer token" \
     http://localhost:27000/api/leo/user/123/departments

Proxy Issues

Error: Trust Proxy Not Working

1. Set TRUST_PROXY=true in .env

2. Verify proxy sends X-Forwarded-Proto header

3. Check X-Forwarded-For header format

Error: HTTPS Redirect Loop

1. Verify TRUST_PROXY=true is set

2. Check proxy sends X-Forwarded-Proto: https

3. Verify FORCE_HTTPS=true only in production

Common Error Messages

Database Errors

Error: Connection refused

• MySQL is not running

• Wrong host/port

• Firewall blocking connection

Error: Access denied

• Wrong username/password

• User doesn't have permissions

Error: Unknown database

• Database doesn't exist

• Wrong database name in .env

Discord Errors

Error: Invalid OAuth2 redirect_uri

• Callback URL mismatch

• URL not registered in Discord portal

Error: Invalid client secret

• Wrong client secret

• Application deleted or regenerated

Error: Missing Permissions

• Bot doesn't have required permissions

• Bot not in server

Application Errors

Error: EBADCSRFTOKEN

• CSRF token mismatch

• Session expired

• Cookie issues

Error: EADDRINUSE

• Port already in use

• Another instance running

Debug Tools

Health Endpoints

• /healthz - Always 200 (process alive)

• /readyz - 200 only if database connected

• /metrics - Performance metrics (if enabled)

Admin Diagnostics

Navigate to /admin/diagnostics for:

• System health check

• Database connection status

• Discord connection status

• Configuration validation

Getting Help

If you're still experiencing issues:

1. Check Common Issues

2. Review Error Messages

3. Check application logs

4. Review database logs

5. Test with minimal configuration

6. Contact support with:

   • Error message

   • Relevant log excerpts

   • Configuration (sanitized)

   • Steps to reproduce