Troubleshooting

Common issues and their solutions.

Quick Diagnostics

Check System Health

# Backend health
curl https://your-server.com/health

# Expected response
{
  "status": "healthy",
  "database": "connected",
  "redis": "connected"
}

Check Logs

# Docker deployment
docker compose logs -f backend

# Manual deployment
tail -f /var/log/slimrmm/backend.log

Common Issues

Agent Issues

Agent Not Registering

Symptoms:

• Agent starts but doesn't appear in dashboard
• "Connection refused" errors

Solutions:

1. Verify server URL:

   curl -I https://your-server.com/health

2. Check firewall:

   # Outbound 443 must be allowed
   nc -zv your-server.com 443

3. Verify enrollment token:

   • Tokens expire after use
   • Check token hasn't been revoked

4. Check agent logs:

   # Linux
   sudo journalctl -u slimrmm-agent -f
   
   # Windows
   Get-EventLog -LogName Application -Source SlimRMMAgent
   
   # macOS
   log show --predicate 'subsystem == "io.slimrmm.agent"'

Agent Shows Offline

Symptoms:

• Agent was online, now shows offline
• Heartbeat not received

Solutions:

1. Check agent service:

   # Linux
   sudo systemctl status slimrmm-agent
   
   # Windows
   Get-Service SlimRMMAgent
   
   # macOS
   sudo launchctl list | grep slimrmm

2. Verify network connectivity:

   curl -I https://your-server.com/health

3. Check certificate validity:

   openssl x509 -in /var/lib/slimrmm/cert.pem -noout -dates

4. Restart agent:

   sudo systemctl restart slimrmm-agent

Windows Service Errors

Error 1072: Service Marked for Deletion

This occurs when Windows still holds a handle to the service after uninstallation.

# Kill lingering processes
taskkill /F /IM slimrmm-agent.exe
taskkill /F /IM slimrmm-helper.exe

# Delete service registration
sc delete SlimRMMAgent

# Wait, then reinstall
Start-Sleep -Seconds 2
cd "C:\Program Files\SlimRMM"
.\slimrmm-agent.exe install -s https://your-server.com

If it persists: close services.msc, restart Explorer, or reboot.

Error 1061: Service Cannot Accept Control Messages

Normal when running agent commands from CLI (not as service). The agent handles this automatically in v2.1.115+.

See Windows Agent Installation for detailed solutions.

Connection Issues

WebSocket Disconnections

Symptoms:

• Agents frequently disconnect
• Real-time updates not working

Solutions:

1. Check reverse proxy config:

   # Nginx - ensure WebSocket support
   location /api/ {
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_read_timeout 86400;  # 24 hours
   }

2. Increase timeouts:

   • Nginx: proxy_read_timeout
   • Load balancer: Idle timeout

3. Check for network issues:

   • Packet loss
   • High latency
   • Firewall timeouts

SSL/TLS Errors

Symptoms:

• "Certificate verify failed"
• "SSL handshake error"

Solutions:

1. Verify certificate:

   openssl s_client -connect your-server.com:443 -servername your-server.com

2. Check certificate chain:

   openssl verify -CAfile ca.pem cert.pem

3. Ensure certificate matches domain:

   openssl x509 -in cert.pem -noout -text | grep DNS

Database Issues

Connection Pool Exhausted

Symptoms:

• "Too many connections"
• Slow responses
• Timeouts

Solutions:

1. Increase pool size:

   # In database configuration
   SQLALCHEMY_POOL_SIZE=20
   SQLALCHEMY_MAX_OVERFLOW=10

2. Check for leaks:

   SELECT count(*) FROM pg_stat_activity WHERE application_name = 'slimrmm';

3. Restart backend:

   docker compose restart backend

Migration Failures

Symptoms:

• "Relation does not exist"
• Schema mismatch errors

Solutions:

1. Run migrations:

   docker compose exec backend alembic upgrade head

2. Check migration history:

   docker compose exec backend alembic history

3. Verify current revision:

   docker compose exec backend alembic current

Performance Issues

High CPU Usage

Symptoms:

• Backend using 100% CPU
• Slow response times

Solutions:

1. Check active connections:

   docker stats slimrmm-backend

2. Review slow queries:

   -- Enable slow query log in PostgreSQL
   ALTER SYSTEM SET log_min_duration_statement = 1000;
   SELECT pg_reload_conf();

3. Scale horizontally:

   • Add more backend instances
   • Use load balancer

Memory Issues

Symptoms:

• Out of memory errors
• Container restarts

Solutions:

1. Increase memory limits:

   # docker-compose.yml
   backend:
     deploy:
       resources:
         limits:
           memory: 2G

2. Check memory usage:

   docker stats --no-stream

3. Review Redis memory:

   docker compose exec redis redis-cli INFO memory

Authentication Issues

Login Fails

Symptoms:

• "Invalid credentials"
• Can't log in

Solutions:

1. Reset password:

   docker compose exec backend python -c "
   from app.core.database import get_db_sync
   from app.services.auth_service import reset_password
   db = next(get_db_sync())
   reset_password(db, 'admin', 'new_password')
   "

2. Check account status:

   • Account may be locked
   • Check database for is_locked flag

MFA Not Working

Symptoms:

• TOTP codes rejected
• WebAuthn fails

Solutions:

1. Check time sync:

   # TOTP is time-based
   ntpdate -q pool.ntp.org

2. Disable MFA (emergency):

   docker compose exec backend python -c "
   from app.core.database import get_db_sync
   from app.models.user import User
   db = next(get_db_sync())
   user = db.query(User).filter_by(username='admin').first()
   user.mfa_enabled = False
   db.commit()
   "

Getting Help

Collect Debug Information

When reporting issues, include:

# System info
uname -a
docker version
docker compose version

# Backend logs (last 100 lines)
docker compose logs --tail=100 backend

# Database status
docker compose exec postgres psql -U rmm -c "SELECT version();"

# Redis status
docker compose exec redis redis-cli INFO server

Support Channels

• Documentation: You're here!
• GitHub Issues: Report bugs
• Email: support@kiefer-networks.de

Debug Mode

Enable debug mode for detailed logs:

# .env
DEBUG=true
LOG_LEVEL=DEBUG

# Restart
docker compose restart backend

WARNING

Never enable debug mode in production with real data!