Troubleshooting Common Issues

Introduction

Deploying Spring Boot applications to AWS Lightsail can involve various moving parts, and issues are bound to arise during the deployment process. This troubleshooting guide covers the most common problems you’ll encounter and provides step-by-step solutions to resolve them quickly.

Understanding how to diagnose and fix deployment issues is crucial for maintaining a reliable production environment. This lesson will equip you with the knowledge and tools to identify problems and implement effective solutions.

Application Won’t Start

Java Version Mismatch

One of the most common issues is running your Spring Boot application with an incompatible Java version.

Symptoms:

  • Application fails to start with UnsupportedClassVersionError
  • JAR file won’t execute
  • Build works locally but fails on server

Solution:

First, check your local Java version and the version specified in your pom.xml:

# Check Java version on your local machine
java -version

# Check Java version on Lightsail instance
ssh -i your-key.pem ubuntu@your-lightsail-ip
java -version

Ensure your pom.xml matches the server’s Java version:

<properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

If you need to update Java on your Lightsail instance:

# Install Java 17
sudo apt update
sudo apt install openjdk-17-jdk

# Set Java 17 as default
sudo update-alternatives --config java
TipPro Tip

Always use the same Java version across your development, build, and production environments to avoid compatibility issues.

Missing Environment Variables

Symptoms:

  • Application starts but database connections fail
  • Configuration properties are not loaded correctly
  • Application behavior differs from local environment

Solution:

Check if your environment variables are properly set:

# View current environment variables
env | grep -i spring

# Check if your application.properties file exists
ls -la /opt/myapp/

Ensure your environment variables are set in the systemd service file:

sudo nano /etc/systemd/system/myapp.service
[Unit]
Description=My Spring Boot Application
After=syslog.target

[Service]
User=ubuntu
ExecStart=/usr/bin/java -jar /opt/myapp/myapp.jar
SuccessExitStatus=143
Environment=SPRING_PROFILES_ACTIVE=production
Environment=DB_HOST=localhost
Environment=DB_PASSWORD=your_secure_password
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Reload and restart the service:

sudo systemctl daemon-reload
sudo systemctl restart myapp

Database Connection Issues

Connection Refused Errors

Symptoms:

  • java.net.ConnectException: Connection refused
  • Application logs show database connection timeouts
  • MySQL service appears to be running but connections fail

Solution:

First, verify MySQL is running and listening on the correct port:

# Check MySQL service status
sudo systemctl status mysql

# Check if MySQL is listening on port 3306
sudo netstat -tlnp | grep 3306

# Test local database connection
mysql -u root -p -h localhost

If MySQL isn’t running, start it:

sudo systemctl start mysql
sudo systemctl enable mysql

Check your database configuration in application-production.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/myapp_db?useSSL=false&serverTimezone=UTC
spring.datasource.username=myapp_user
spring.datasource.password=${DB_PASSWORD}
spring.jpa.database-platform=org.hibernate.dialect.MySQL8Dialect

Authentication Failures

Symptoms:

  • Access denied for user 'username'@'host'
  • Database user exists but authentication fails

Solution:

Verify database user permissions:

-- Log into MySQL as root
mysql -u root -p

-- Check user privileges
SHOW GRANTS FOR 'myapp_user'@'localhost';

-- If user doesn't exist or lacks privileges, recreate it
DROP USER IF EXISTS 'myapp_user'@'localhost';
CREATE USER 'myapp_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON myapp_db.* TO 'myapp_user'@'localhost';
FLUSH PRIVILEGES;
WarningSecurity Warning

Never use the root MySQL user for your application. Always create a dedicated user with minimal required privileges.

Nginx Configuration Problems

502 Bad Gateway Error

Symptoms:

  • Nginx returns “502 Bad Gateway” error
  • Application is running but not accessible through Nginx
  • Direct access to application port works

Solution:

Check if your Spring Boot application is running on the expected port:

# Check if application is listening on port 8080
sudo netstat -tlnp | grep 8080

# Check application logs
sudo journalctl -u myapp -f

Verify your Nginx configuration:

sudo nano /etc/nginx/sites-available/myapp

Ensure the proxy_pass directive points to the correct port:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout       600;
        proxy_send_timeout          600;
        proxy_read_timeout          600;
        send_timeout                600;
    }
}

Test and reload Nginx configuration:

# Test configuration syntax
sudo nginx -t

# Reload Nginx if test passes
sudo systemctl reload nginx

SSL Certificate Issues

Symptoms:

  • “Your connection is not secure” warnings
  • Certificate expired or invalid errors
  • Mixed content warnings

Solution:

Check certificate status:

# Check certificate expiration
sudo certbot certificates

# Test SSL configuration
openssl s_client -connect your-domain.com:443

Renew certificates if needed:

# Test certificate renewal (dry run)
sudo certbot renew --dry-run

# Renew certificates
sudo certbot renew

# Restart Nginx
sudo systemctl restart nginx

Performance and Memory Issues

Out of Memory Errors

Symptoms:

  • java.lang.OutOfMemoryError
  • Application becomes unresponsive
  • High memory usage in system monitoring

Solution:

Check current memory usage:

# Check system memory
free -h

# Check Java process memory usage
ps aux | grep java

Adjust JVM memory settings in your systemd service:

sudo nano /etc/systemd/system/myapp.service
[Service]
ExecStart=/usr/bin/java -Xms512m -Xmx1024m -jar /opt/myapp/myapp.jar
NoteMemory Guidelines

For Lightsail instances with 1GB RAM, allocate a maximum of 768MB to your Java application to leave memory for the operating system and other services.

Slow Application Performance

Symptoms:

  • Long response times
  • Database queries timing out
  • High CPU usage

Solution:

Enable application performance monitoring:

# Add to application-production.properties
management.endpoints.web.exposure.include=health,metrics,info
management.endpoint.health.show-details=always

Check database performance:

-- Enable MySQL slow query log
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

-- Check for slow queries
SHOW PROCESSLIST;

Optimize database connections:

# Database connection pool settings
spring.datasource.hikari.maximum-pool-size=5
spring.datasource.hikari.minimum-idle=2
spring.datasource.hikari.connection-timeout=20000
spring.datasource.hikari.idle-timeout=300000
spring.datasource.hikari.max-lifetime=1200000

Debugging Tools and Commands

Essential Log Files

Monitor these key log locations for troubleshooting:

# Application logs (systemd)
sudo journalctl -u myapp -f

# Nginx access logs
sudo tail -f /var/log/nginx/access.log

# Nginx error logs
sudo tail -f /var/log/nginx/error.log

# MySQL error logs
sudo tail -f /var/log/mysql/error.log

# System logs
sudo tail -f /var/log/syslog

Useful Diagnostic Commands

# Check service status
sudo systemctl status myapp
sudo systemctl status nginx
sudo systemctl status mysql

# Check port usage
sudo netstat -tlnp | grep -E ':(80|443|3306|8080)'

# Check disk space
df -h

# Check system resources
top
htop

# Test network connectivity
curl -I http://localhost:8080/actuator/health
TipDebugging Strategy

Always start with the application logs, then work your way through the stack (database, web server, network) to isolate the issue.

Summary

Troubleshooting Spring Boot applications on AWS Lightsail requires a systematic approach to identify and resolve issues. The most common problems fall into several categories:

Key Troubleshooting Areas:

  • Java Runtime Issues: Version mismatches and missing dependencies
  • Database Connectivity: Connection configuration and authentication problems
  • Web Server Configuration: Nginx proxy settings and SSL certificates
  • Resource Constraints: Memory allocation and performance optimization

Essential Troubleshooting Tools:

  • System logs (journalctl, log files)
  • Network diagnostics (netstat, curl)
  • Service management (systemctl)
  • Resource monitoring (top, free, df)

Best Practices:

  • Monitor application logs regularly
  • Test configurations before applying changes
  • Keep backups of working configurations
  • Document solutions for future reference
  • Use consistent environments across development and production

By mastering these troubleshooting techniques, you’ll be able to quickly diagnose and resolve most deployment issues, ensuring your Spring Boot application runs reliably on AWS Lightsail.