How to Quickly Diagnose Spring Boot + Nacos + MySQL Startup Failures

Scenario

You have a Java microservice (e.g., your-pro.jar) deployed on a Linux server using Spring Boot, Nacos as configuration and registry center, and MySQL as the database. The application fails to start or is unreachable, and you need a fast diagnosis.

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

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

Step 2: Confirm the Application Is Running

# Check Java processes
ps aux | grep java | grep -v grep

# Or search for your specific service
ps aux | grep your-pro

Typical output shows a line like java -jar your-pro.jar. No output means 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: 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 endpoint
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 causes include firewall blockage, cloud security group restrictions, or the 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" >/dev/null

# View bootstrap.yml content (focus on DB and Nacos)
cat /home/project-cloud/server/your-pro/module/config/bootstrap.yml

# Verify datasource configuration
grep -A 5 -B 2 "datasource" bootstrap.yml

Ensure the file contains sections like:

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

# Retrieve config from Nacos (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 you defined 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';

# List 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 remote access.

Step 8: Inspect System Resources

# CPU and memory
top -b -n 1 | head -20

# Disk space
df -h / /home

# Log directory size
du -sh /home/project-cloud/server/*/logs/*.log

Insufficient disk space can cause log write failures and application crashes.

Step 9: Verify Service Startup Command

# Find how you started the service
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 present and no required JVM arguments (e.g., -Dnacos.server.addr=...) are missing.

Step 10: One‑Click Diagnostic Script (Optional)

#!/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 errors"
tail -n 20 /home/project-cloud/server/your-pro/module/logs/*.log | grep -E "ERROR|WARN"

Run the script with chmod +x diagnose.sh && ./diagnose.sh > diagnose.log and share the log with teammates for rapid issue location.

Summary Flowchart

Startup failure?
  ↓
→ Check logs (tail -f)
  ↓
→ Check process (ps aux)
  ↓
→ Check ports (ss -tulnp)
  ↓
→ Test connectivity (telnet/curl)
  ↓
→ Verify configs (bootstrap.yml + Nacos)
  ↓
→ Validate database
  ↓
→ Inspect resources (CPU/memory/disk)
  ↓
→ Fix and restart