Quickly Diagnose Spring Boot + Nacos + MySQL Microservice Failures

Scenario

You have a Java microservice packaged as your-pro.jar that runs on a Linux server. The service uses Spring Boot, Nacos for configuration and service discovery, and MySQL as the database. Log files are stored in /home/project-cloud/server/your-pro/module/logs/. The following checklist helps diagnose common problems such as startup failure, connection timeout, or missing configuration.

Step 1: Check Application Logs

# cd /home/project-cloud/server/your-pro/module/logs/
# tail -f *.log | grep --color=always -E "ERROR|WARN|Exception"

Typical error keywords to look for: Failed to start , DataSource , Connection refused , Timeout , ClassNotFoundException , NoSuchBeanDefinitionException .

Step 2: Verify the Process Is Running

# ps aux | grep java | grep -v grep
# ps aux | grep your-pro

Example of a successful Java process line:

root 1234 1.2 5.3 2345678 123456 ? Sl 10:00 0:15 java -jar your-pro.jar

Step 3: Check Listening Ports

# ss -tulnp | grep :9202   # service port
# ss -tulnp | grep :8848   # Nacos HTTP port
# ss -tulnp | grep :9848   # Nacos gRPC port
# ss -tulnp | grep :3306   # MySQL port

The command should show a LISTEN state with the corresponding java or mysqld process. No output means the service is not listening or the port is mis‑configured.

Step 4: Test Network Connectivity

# curl -s -w "%{http_code}
" -o /dev/null http://10.135.10.33:8848/nacos/v1/console/health
# telnet 10.135.10.33 9848
# telnet 127.0.0.1 3306
# curl http://localhost:9202/actuator/health

If any command fails, investigate firewall rules, cloud security‑group settings, or that the service is bound to the expected IP address.

Step 5: Inspect Configuration Files

# find /home/project-cloud -name "bootstrap*.yml" -o -name "application*.yml" 2>/dev/null
# cat /home/project-cloud/server/your-pro/module/config/bootstrap.yml
# grep -A 5 -B 2 "datasource" bootstrap.yml

Typical YAML fragment required for the service:

spring:
  datasource:
    url: jdbc:mysql://...
    username: ...
    password: ...
  cloud:
    nacos:
      discovery:
        server-addr: 10.135.10.33:8848
      config:
        server-addr: 10.135.10.33:8848

Step 6: Verify Nacos Configuration Exists

# curl "http://10.135.10.33:8848/nacos/v1/cs/configs?dataId=your-pro-test.yml&group=DEFAULT_GROUP"
# curl -u nacos:nacos "http://10.135.10.33:8848/nacos/v1/cs/configs?dataId=your-pro-test.yml&group=DEFAULT_GROUP"

The response should be the YAML content stored in Nacos, including the database settings.

Step 7: Check MySQL Connectivity

# mysql -h 127.0.0.1 -u root -p
SHOW DATABASES LIKE 'your_pro';
USE your_pro;
SHOW TABLES;

If the connection fails, verify that MySQL is running, the user has sufficient privileges, and the bind-address does not restrict the client IP.

Step 8: Examine System Resources

# top -b -n 1 | head -20
# df -h / /home
# du -sh /home/project-cloud/server/*/logs/*.log

Ensure there is enough free disk space and memory; a full disk can prevent log writing or cause the application to crash.

Step 9: Review Service Startup Command

# ps aux | grep java | grep jar
# java -jar your-pro.jar --spring.profiles.active=test

Confirm that the correct Spring profile is activated and that required JVM arguments (e.g., --spring.profiles.active, -Dnacos.server.addr=...) are present.

Step 10: Optional One‑Click Diagnostic Script

#!/bin/bash

echo "=== Diagnosis time: $(date) ==="

echo "【1. Java processes】"
ps aux | grep java | grep -v grep

echo "【2. Port listening】"
ss -tulnp | grep -E ":(8848|9848|9202|3306)"

echo "【3. Nacos health】"
curl -s http://10.135.10.33:8848/nacos/v1/console/health

echo "【4. Disk space】"
df -h /

echo "【5. Recent logs】"
tail -n 20 /home/project-cloud/server/your-pro/module/logs/*.log | grep -E "ERROR|WARN"

Make the script executable with chmod +x diagnose.sh and run it, redirecting output to a file (e.g., ./diagnose.sh > diagnose.log) for quick sharing with teammates.