Quickly Diagnose Spring Boot + Nacos + MySQL Microservice Failures

Scenario

The following applies to a Spring Boot + Nacos + MySQL microservice architecture with common issues such as startup failure, connection timeout, or missing configuration.

Nacos as configuration and registration center

MySQL as database

Spring Boot framework

Log files located at /home/project-cloud/server/your-pro/module/logs/ You notice the application fails to start or is inaccessible and need a fast investigation.

Custom Troubleshooting Command Template: Spring Boot + Nacos + MySQL

It is recommended to execute the steps in order; each step may pinpoint the problem.

Step 1: View Application Logs (Locate Error Root Cause)

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

Key keywords to watch for:

Failed to start

DataSource

Connection refused

Timeout

ClassNotFoundException

NoSuchBeanDefinitionException

Step 2: Confirm Application Is Running

# Check Java processes
ps aux | grep java | grep -v grep
# Or precise search
ps aux | grep your-pro

Normal output example:

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

If there is no output, the service is not started or has crashed.

Step 3: Check Port Listening

# Check your service port (e.g., 9202)
ss -tulnp | grep :9202
# Check Nacos ports
ss -tulnp | grep :8848
ss -tulnp | grep :9848
# Check MySQL port
ss -tulnp | grep :3306

Normal: shows LISTEN state with java or mysqld process

Abnormal: no output → service not started or port misconfiguration

Step 4: Test Network Connectivity

# Test Nacos HTTP health
curl -s -w "%{http_code}
" -o /dev/null http://10.135.10.33:8848/nacos/v1/console/health
# Test Nacos gRPC port
telnet 10.135.10.33 9848
# Test MySQL connectivity
telnet 127.0.0.1 3306
# Test local service response
curl http://localhost:9202/actuator/health

If telnet fails, possible reasons include firewall blockage, cloud security group not opened, or the service not listening.

Firewall blocking

Security group not open (cloud server)

Service not listening

Step 5: Check Configuration Files

# Find bootstrap.yml or application.yml
find /home/project-cloud -name "bootstrap*.yml" -o -name "application*.yml" 2>/dev/null
# View configuration content (focus on DB and Nacos)
cat /home/project-cloud/server/your-pro/module/config/bootstrap.yml
# Check datasource configuration
grep -A 5 -B 2 "datasource" bootstrap.yml

Ensure the configuration contains:

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

# Fetch Nacos config (replace dataId and group)
curl "http://10.135.10.33:8848/nacos/v1/cs/configs?dataId=your-pro-test.yml&group=DEFAULT_GROUP"
# With authentication if needed
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 configured in the Nacos console, including database settings.

Step 7: Check Database Connection

# Login to MySQL
mysql -h 127.0.0.1 -u root -p
# Verify database existence
SHOW DATABASES LIKE 'your_pro';
# Verify tables (if using code generator)
USE your_pro;
SHOW TABLES;

If connection fails, check whether MySQL is running, user permissions, and whether bind-address restricts the IP.

MySQL is started

User privileges bind-address restrictions

Step 8: Check System Resources

# CPU and memory
top -b -n 1 | head -20
# Disk space
df -h / /home
# Log directory usage
du -sh /home/project-cloud/server/*/logs/*.log

Avoid disk full causing log write failures or application crashes.

Step 9: Verify Service Startup Command

# Find how you started it
ps aux | grep java | grep jar
# Correct example
java -jar your-pro.jar --spring.profiles.active=test

Make sure the --spring.profiles.active flag is used and no required JVM parameters (e.g., -Dnacos.server.addr=...) are missing.

Step 10: One‑Click Package Diagnostic Information (Optional)

Create a script diagnose.sh:

#!/bin/bash
echo "=== Diagnosis Time: $(date) ==="
echo

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

echo

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

echo

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

echo

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

echo

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

Run the script and redirect output:

chmod +x diagnose.sh
./diagnose.sh > diagnose.log

Share the diagnose.log with colleagues for rapid issue localization.

Summary: Troubleshooting Flowchart