CORS Issues

CORS (Cross-Origin Resource Sharing) issues occur when the frontend (running on one origin) tries to make requests to the backend API (running on a different origin). This guide helps you understand and resolve CORS errors.

Understanding CORS

In development, the frontend runs on http://localhost:5173 (Vite) and the backend on http://localhost:8080 (Spring Boot). These are different origins, so CORS must be configured.

Current CORS Configuration

The application’s CORS settings are configured in SecurityConfig.java:55-68:

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(Arrays.asList(
        "http://localhost:5173", 
        "http://127.0.0.1:5173"
    ));
    configuration.setAllowedMethods(Arrays.asList(
        "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"
    ));
    configuration.setAllowedHeaders(Arrays.asList(
        "Authorization", "Content-Type", "X-Requested-With", 
        "Accept", "Origin", "Access-Control-Request-Method", 
        "Access-Control-Request-Headers"
    ));
    configuration.setExposedHeaders(Arrays.asList("Authorization"));
    configuration.setAllowCredentials(true);
    configuration.setMaxAge(3600L);

    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", configuration);
    return source;
}

Common CORS Errors

CORS policy: No 'Access-Control-Allow-Origin' header

Error in Browser Console:

Access to XMLHttpRequest at 'http://localhost:8080/api/productos' 
from origin 'http://localhost:5173' has been blocked by CORS policy: 
No 'Access-Control-Allow-Origin' header is present on the requested resource.

Causes:

Frontend origin not in allowed origins list
CORS configuration not applied to all endpoints
Backend not running or crashed

Solutions:

Verify frontend URL matches allowed origins:
- Check the URL in your browser address bar
- Must be exactly http://localhost:5173 or http://127.0.0.1:5173
Add your origin to SecurityConfig.java:

configuration.setAllowedOrigins(Arrays.asList(
    "http://localhost:5173",
    "http://127.0.0.1:5173",
    "http://localhost:3000" // Add if using different port
));

For development, allow all origins (NOT for production):

configuration.setAllowedOriginPatterns(Arrays.asList("*"));
// Instead of setAllowedOrigins

Verify CORS is applied globally:
- Check that corsConfigurationSource() bean is defined
- Ensure it’s registered in the security filter chain
Restart the backend after changes:

cd Iqüea_back
mvn spring-boot:run

Never use setAllowedOriginPatterns("*") with setAllowCredentials(true) in production. Always specify exact origins.

CORS policy: Request header field Authorization not allowed

Error Message:

Access to XMLHttpRequest at 'http://localhost:8080/api/pedidos' 
from origin 'http://localhost:5173' has been blocked by CORS policy: 
Request header field authorization is not allowed by 
Access-Control-Allow-Headers in preflight response.

Cause: The Authorization header is not in the allowed headers list.Solution:

Verify allowed headers include Authorization:
- Check SecurityConfig.java:59-61
- Should include: "Authorization"
If missing, add it:

configuration.setAllowedHeaders(Arrays.asList(
    "Authorization",  // Must be included
    "Content-Type", 
    "X-Requested-With", 
    "Accept",
    "Origin"
));

Or allow all headers (development only):

configuration.setAllowedHeaders(Arrays.asList("*"));

Ensure frontend sends correct header format:

fetch('http://localhost:8080/api/pedidos', {
  headers: {
    'Authorization': `Bearer ${token}`, // Correct format
    'Content-Type': 'application/json'
  }
})

CORS policy: Method not allowed

Error Message:

Access to XMLHttpRequest at 'http://localhost:8080/api/productos/1' 
from origin 'http://localhost:5173' has been blocked by CORS policy: 
Method DELETE is not allowed by Access-Control-Allow-Methods.

Cause: The HTTP method is not in the allowed methods list.Solution:

Check allowed methods in SecurityConfig.java:58:

configuration.setAllowedMethods(Arrays.asList(
    "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"
));

Verify the method is included - all common methods should be there
If needed, add missing method:

configuration.setAllowedMethods(Arrays.asList(
    "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH", "HEAD"
));

Always include OPTIONS for preflight requests

CORS preflight request fails (OPTIONS)

Error Message:

Access to XMLHttpRequest at 'http://localhost:8080/api/productos' 
from origin 'http://localhost:5173' has been blocked by CORS policy: 
Response to preflight request doesn't pass access control check.

What is a preflight request?Browsers send an OPTIONS request before certain requests (those with custom headers or methods other than GET/POST) to check if the actual request is allowed.Solutions:

Ensure OPTIONS method is allowed:

configuration.setAllowedMethods(Arrays.asList(
    "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"
));

Set maxAge to cache preflight responses:

configuration.setMaxAge(3600L); // Cache for 1 hour

Already configured in line 63

Check that CSRF is disabled (required for CORS):
- In SecurityConfig.java:27:

http.csrf(csrf -> csrf.disable())

Verify OPTIONS requests aren’t blocked by security:
- OPTIONS requests should not require authentication
Check browser DevTools Network tab:
- Look for OPTIONS request
- Check response headers:
  - Access-Control-Allow-Origin
  - Access-Control-Allow-Methods
  - Access-Control-Allow-Headers

Credentials mode issues

Error Message:

Access to XMLHttpRequest at 'http://localhost:8080/api/auth/login' 
from origin 'http://localhost:5173' has been blocked by CORS policy: 
The value of the 'Access-Control-Allow-Credentials' header in the response 
is '' which must be 'true' when the request's credentials mode is 'include'.

Cause: Mismatch between frontend credentials setting and backend CORS configuration.Solutions:

Backend: Ensure credentials are allowed:
- Check SecurityConfig.java:62:

configuration.setAllowCredentials(true);

Frontend: Send credentials if needed:

fetch('http://localhost:8080/api/auth/login', {
  method: 'POST',
  credentials: 'include', // Sends cookies
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email, password })
})

If not using cookies, omit credentials:

// If using JWT in localStorage, credentials not needed
fetch('http://localhost:8080/api/productos', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('token')}`
  }
  // No credentials: 'include' needed
})

Iquea Commerce uses JWT tokens stored in localStorage, so credentials: 'include' is typically not needed unless you’re also using cookies.

Development vs Production

CORS configuration for different environments

Development Configuration:Allow localhost origins:

configuration.setAllowedOrigins(Arrays.asList(
    "http://localhost:5173",
    "http://127.0.0.1:5173",
    "http://localhost:3000"
));

Production Configuration:

Use environment variables:

@Value("${app.cors.allowed-origins}")
private String allowedOrigins;

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(
        Arrays.asList(allowedOrigins.split(","))
    );
    // ... rest of configuration
}

In application.properties:

# Development
app.cors.allowed-origins=http://localhost:5173,http://127.0.0.1:5173

# Production (application-prod.properties)
app.cors.allowed-origins=https://iquea.com,https://www.iquea.com

Security best practices:
- Always use HTTPS in production
- Specify exact domains (no wildcards)
- Keep credentials enabled only if needed
- Set appropriate maxAge for caching

Example Production Configuration:

if (environment.equals("production")) {
    configuration.setAllowedOrigins(Arrays.asList(
        "https://iquea.com",
        "https://www.iquea.com"
    ));
} else {
    configuration.setAllowedOriginPatterns(Arrays.asList("*"));
}

Nginx/Apache proxy CORS configuration

If using a reverse proxy in production:Nginx:

location /api {
    proxy_pass http://localhost:8080;
    
    # Let Spring Boot handle CORS
    proxy_set_header Origin $http_origin;
    proxy_set_header Host $host;
    
    # Or handle CORS in Nginx
    add_header Access-Control-Allow-Origin $http_origin always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
    add_header Access-Control-Allow-Credentials true always;
    
    if ($request_method = OPTIONS) {
        return 204;
    }
}

Apache:

<Location /api>
    ProxyPass http://localhost:8080/api
    ProxyPassReverse http://localhost:8080/api
    
    Header set Access-Control-Allow-Origin "%{HTTP_ORIGIN}e"
    Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
    Header set Access-Control-Allow-Headers "Authorization, Content-Type"
    Header set Access-Control-Allow-Credentials "true"
</Location>

If configuring CORS in your proxy, disable or adjust the Spring Boot CORS configuration to avoid conflicts.

Debugging CORS Issues

Browser DevTools

Open DevTools (F12) → Network tab
Reproduce the error
Look for the failed request
Check Request Headers:
- Origin: http://localhost:5173
- Access-Control-Request-Method: POST (for preflight)
- Access-Control-Request-Headers: authorization (for preflight)
Check Response Headers:
- Access-Control-Allow-Origin: http://localhost:5173
- Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
- Access-Control-Allow-Headers: Authorization, Content-Type
- Access-Control-Allow-Credentials: true

Testing with cURL

# Test preflight request
curl -X OPTIONS http://localhost:8080/api/productos \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Authorization, Content-Type" \
  -v

# Test actual request
curl -X GET http://localhost:8080/api/productos \
  -H "Origin: http://localhost:5173" \
  -v

Look for Access-Control-* headers in the response.

Common Mistakes

Common CORS configuration mistakes:

Using http://localhost:5173/ (with trailing slash) - should be http://localhost:5173
Forgetting to restart backend after configuration changes
Using wildcards with credentials in production
Not including OPTIONS in allowed methods
Blocking OPTIONS requests with authentication
Typos in header names (e.g., Authorisation instead of Authorization)
Testing with browser extensions that modify headers
Configuring CORS in multiple places (proxy + Spring Boot)

Quick Checklist

When troubleshooting CORS issues:

Additional Resources

Common Issues - General troubleshooting
Database Errors - Database issues
MDN CORS Documentation
Spring Security CORS

Database Errors

⌘I

Contributing

Deployment

Troubleshooting

Understanding CORS

Current CORS Configuration

Common CORS Errors

Development vs Production

Debugging CORS Issues

Browser DevTools

Testing with cURL

Common Mistakes

Quick Checklist

Additional Resources

Build docs developers (and LLMs) love

Contributing

Deployment

Troubleshooting

​Understanding CORS

​Current CORS Configuration

​Common CORS Errors

​Development vs Production

​Debugging CORS Issues

​Browser DevTools

​Testing with cURL

​Common Mistakes

​Quick Checklist

​Additional Resources

Build docs developers (and LLMs) love

Understanding CORS

Current CORS Configuration

Common CORS Errors

Development vs Production

Debugging CORS Issues

Browser DevTools

Testing with cURL

Common Mistakes

Quick Checklist

Additional Resources