# INTERNAL: grpc-web: CORS preflight failed for origin http://localhost:3000

- **ID:** `grpc/grpc-web-cors-failure`
- **Domain:** grpc
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

The gRPC-Web proxy or server did not respond with the correct CORS headers for the preflight OPTIONS request.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Envoy 1.26.0 | active | — | — |
| gRPC-Web 1.48.0 | active | — | — |

## Workarounds

1. **Configure the gRPC-Web proxy (e.g., Envoy) to add CORS headers. Example Envoy config snippet: `cors: { allow_origin_string_match: [{ prefix: "http://localhost:3000" }], allow_methods: "POST, OPTIONS", allow_headers: "content-type,x-grpc-web", max_age: "86400" }`** (90% success)
   ```
   Configure the gRPC-Web proxy (e.g., Envoy) to add CORS headers. Example Envoy config snippet: `cors: { allow_origin_string_match: [{ prefix: "http://localhost:3000" }], allow_methods: "POST, OPTIONS", allow_headers: "content-type,x-grpc-web", max_age: "86400" }`
   ```
2. **If using a custom server, handle OPTIONS requests manually by returning 200 with appropriate CORS headers.** (85% success)
   ```
   If using a custom server, handle OPTIONS requests manually by returning 200 with appropriate CORS headers.
   ```

## Dead Ends

- **** — Browsers enforce CORS; it cannot be disabled client-side. (100% fail)
- **** — The preflight request (OPTIONS) must be handled explicitly, not just the POST. (60% fail)
- **** — This only works for non-browser environments; the error is specific to browser-based gRPC-Web. (50% fail)