Chapter 2: Troubleshooting and Problem Solving

Objectives

• Identify and resolve common issues
• Use the project's troubleshooting guides
• Master Spring Boot debugging techniques

---

Main Resource

Official Documentation

All troubleshooting guides are available in the repository:

** Troubleshooting Folder**

---

List of Available Guides

The troubleshooting folder contains numerous numbered guides to assist you:

Guide	Subject	Description
01-xx	Initial Configuration	Project setup
10-xx	Database	PostgreSQL, H2, connections
15-xx	Spring Security	Security configuration
20-xx	JWT	Tokens, authentication
25-xx	REST API	Endpoints, CORS
27	Frontend Codespaces	Frontend integration
28-xx	Tests	Unit and integration tests

---

Common Issues and Solutions

1. Application Startup Error

Symptom

***************************
APPLICATION FAILED TO START
***************************

Possible Causes and Solutions

Database not configured:

# application.yml - H2 configuration for development
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true

Port already in use:

# Check the port
lsof -i :8080

# Use another port
./mvnw spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

---

2. Error 401 Unauthorized

Symptom

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required"
}

Solution

The endpoint requires a JWT token. Follow these steps:

# 1. Register (if endpoint available)
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@test.com", "password": "password123"}'

# 2. Log in to get the token
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@test.com", "password": "password123"}'

# 3. Use the received token
curl http://localhost:8080/api/admin/leads \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

3. CORS Error

Symptom (in the browser console)

Access to fetch at 'http://localhost:8080/api/contact' from origin 
'http://localhost:3000' has been blocked by CORS policy

Solution

Check the CORS configuration in SecurityConfig.java:

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(Arrays.asList("*"));
    configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE"));
    configuration.setAllowedHeaders(Arrays.asList("*"));
    
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", configuration);
    return source;
}

---

4. Validation Error

Symptom

{
  "status": 400,
  "errors": {
    "email": "must be a valid email",
    "fullName": "must not be blank"
  }
}

Solution

Check the data being sent. All required fields must be present:

{
  "fullName": "Full Name",        // Required
  "email": "valid@email.com",     // Required, email format
  "company": "Optional",          // Optional
  "phone": "Optional",            // Optional
  "requestType": "INFO",          // Required: INFO, QUOTE, SUPPORT, PARTNERSHIP, OTHER
  "message": "At least 10 characters minimum for this message"  // Required
}

---

5. PostgreSQL Database Issue

Symptom

Connection to localhost:5432 refused

Solutions

Option A - Use H2 in development:

# application.yml
spring:
  profiles:
    active: dev
    
---
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:h2:mem:testdb

Option B - Run PostgreSQL with Docker:

docker run -d \
  --name postgres-econtact \
  -e POSTGRES_DB=econtactdb \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:14-alpine

---

6. Expired JWT Token

Symptom

{
  "status": 401,
  "error": "Token expired"
}

Solution

Log in again to get a new token:

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "password": "yourpassword"}'

---

7. Error 500 Internal Server Error

Diagnostic

1. Check the logs:

# In the terminal where the application is running
# Stack traces appear automatically

2. Enable debug logs:

# application.yml
logging:
  level:
    com.example.econtact: DEBUG
    org.springframework.security: DEBUG

3. Check the H2 console:
   • URL: http://localhost:8080/h2-console
   • JDBC URL: jdbc:h2:mem:testdb

---

🛠️ Debugging Tools

Postman / Insomnia

Import the Postman collection from the repository to easily test all endpoints.

H2 Console

Accessible at http://localhost:8080/h2-console to inspect the database.

Spring Boot Logs

# Enable detailed logs
logging:
  level:
    root: INFO
    com.example.econtact: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG

Actuator (if enabled)

# Check application health
curl http://localhost:8080/actuator/health

# View loaded beans
curl http://localhost:8080/actuator/beans

---

Specific Guide: Frontend with Codespaces

Essential Guide

For frontend integration in the Codespaces environment, refer to the detailed guide:

** 27-guide-formulaire-frontend-codespaces.md**

---

Debugging Checklist

Before asking for help, check:

• Error logs in the terminal
• Configuration in application.yml
• Database availability
• Format of sent data (valid JSON)
• Presence of JWT token for protected endpoints
• CORS configuration for frontend calls

---

Next Step

Chapter 3: Frontend Integration →

---

Back to module index