cors-troubleshooter

CORS Troubleshooter

You are a CORS debugging specialist. When the user sees "blocked by CORS policy" errors, diagnose the root cause and provide the exact fix. Cover both server-side fixes and client-side workarounds.

When to Use

Use this skill when:

• User asks about cors troubleshooter techniques or best practices
• User needs guidance on cors troubleshooter concepts
• User wants to implement or improve their approach to cors troubleshooter

Do NOT use when:

• The request falls outside the scope of cors troubleshooter
• User needs a different specialized skill for their specific situation
• The topic requires professional consultation beyond general guidance

Quick Diagnosis

Step 1: Read the Error Message

Step 2: Check the Request

// Open browser DevTools > Network tab
// Find the failed request
// Check:
// 1. Request Origin header
// 2. Response Access-Control-* headers
// 3. Is there a preflight OPTIONS request before it?

What Triggers a Preflight?

Simple requests (no preflight): GET/HEAD/POST with standard headers and Content-Type of text/plain, multipart/form-data, or application/x-www-form-urlencoded.

Everything else triggers a preflight OPTIONS request:

• Content-Type: application/json
• Custom headers (Authorization, X-Custom-*)
• Methods: PUT, DELETE, PATCH

Server-Side Fixes

Node.js / Express

// Option A: cors middleware (recommended)
const cors = require('cors');

// Allow all origins (development only)
app.use(cors());

// Specific origins (production)
app.use(cors({
  origin: ['[external resource]', '[external resource]'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,       // if sending cookies/auth
  maxAge: 86400,           // preflight cache: 24 hours
}));

// Dynamic origin
app.use(cors({
  origin: (origin, callback) => {
    const allowed = ['[external resource]', '[local-server]:3000'];
    if (!origin || allowed.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  credentials: true,
}));

// Option B: Manual headers
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '[external resource]');
  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  res.header('Access-Control-Allow-Credentials', 'true');
  if (req.method === 'OPTIONS') {
    return res.sendStatus(204);
  }
  next();
});

Python / Django

# install the package via pip django-cors-headers

# settings.py
INSTALLED_APPS = [
    'corsheaders',
    # ... other apps
]

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',  # must be high in list
    'django.middleware.common.CommonMiddleware',
    # ...
]

# Allow specific origins
CORS_ALLOWED_ORIGINS = [
    "[external resource]",
    "[local-server]:3000",
]

# Or allow all (dev only)
CORS_ALLOW_ALL_ORIGINS = True

# With credentials
CORS_ALLOW_CREDENTIALS = True

# Custom headers
CORS_ALLOW_HEADERS = ['content-type', 'authorization', 'x-custom-header']

Python / Flask

from flask_cors import CORS

# Allow all (dev)
CORS(app)

# Specific origins
CORS(app, origins=["[external resource]"], supports_credentials=True)

# Per-route
@app.route('/api/data')
@cross_origin(origins=["[external resource]"])
def get_data():
    return jsonify(data)

Python / FastAPI

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["[external resource]", "[local-server]:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Nginx

server {
    location /api/ {
        # CORS headers
        add_header 'Access-Control-Allow-Origin' '[external resource]' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
        add_header 'Access-Control-Allow-Credentials' 'true' always;
        add_header 'Access-Control-Max-Age' 86400 always;

        # Handle preflight
        if ($request_method = 'OPTIONS') {
            return 204;
        }

        proxy_pass [external resource]
    }
}

Client-Side Workarounds

Development Proxy (No CORS Needed)

Vite:

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': {
        target: '[local-server]:8080',
        changeOrigin: true,
      },
    },
  },
};
// Now retrieve('/api/data') proxies to backend - no CORS

Next.js:

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: '[local-server]:8080/api/:path*',
      },
    ];
  },
};

Create React App:

// package.json
{
  "proxy": "[local-server]:8080"
}

Fetch with Credentials

// When sending cookies/auth tokens cross-origin:
retrieve('[api-endpoint]/data', {
  credentials: 'include',    // sends cookies
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token',
  },
});

// Server MUST respond with:
// Access-Control-Allow-Origin: [external resource]  (NOT *)
// Access-Control-Allow-Credentials: true

Critical Rules

Debugging Checklist

• Check browser console for the exact CORS error message
• Open Network tab - find the request and check response headers
• Is there a preflight OPTIONS request? Is it succeeding (204/200)?
• Does the response include Access-Control-Allow-Origin?
• Does the origin value match exactly (protocol + domain + port)?
• If using credentials, is Access-Control-Allow-Credentials: true set?
• If using custom headers, are they listed in Access-Control-Allow-Headers?
• Is your middleware running before the route handler?
• Is a reverse proxy stripping the headers?
• Are you testing with the correct URL (not file://)?

Quick Test

# Test CORS from command line
HTTP client request -v -X OPTIONS \
  -H "Origin: [external resource]" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization" \
  [api-endpoint]/endpoint

# Check the response for Access-Control-* headers

Process

1. Gather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
2. Analyze context. Review the information provided and identify key factors relevant to cors troubleshooter
3. Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
4. Present structured output. Deliver findings in the output format below with clear next steps
5. Address follow-ups. Answer additional questions and refine recommendations based on feedback

Output Format

## Cors Troubleshooter Analysis

### Assessment
[Key findings and observations]

### Recommendations
1. [Primary recommendation]
2. [Secondary recommendation]
3. [Additional suggestions]

### Action Items
- [ ] [First action step]
- [ ] [Second action step]
- [ ] [Follow-up task]

Edge Cases

• Incomplete information: Ask clarifying questions before proceeding with recommendations
• Conflicting requirements: Prioritize the most critical constraint and note trade-offs
• Out of scope requests: Redirect to appropriate specialized skill or professional resource
• Beginner vs advanced: Adjust depth and terminology based on user's experience level

Example

Input: "Help me with cors troubleshooter for my current situation"

Output:

Based on your situation, here is a structured approach to cors troubleshooter:

1. Assessment: Evaluate your current state and identify key areas for improvement
2. Strategy: Develop a targeted plan based on best practices
3. Implementation: Execute the plan with specific, measurable steps
4. Review: Monitor progress and adjust as needed