TypeError: Failed to Fetch: Causes, Diagnosis, and Complete Fix Guide

TypeError: Failed to fetch occupies a specific point in the request lifecycle: it occurs when the browser cannot complete the network transaction and receive any HTTP response. This distinguishes it sharply from HTTP error responses like 404 Not Found or 500 Internal Server Error, which arrive as HTTP responses and do not cause fetch to throw. A TypeError means the browser gave up before the server ever sent back a status code.

CORS, or Cross-Origin Resource Sharing, is the most common cause of this error in browser-based applications. When a browser makes a cross-origin fetch — a request to a different domain, port, or protocol than the page's own origin — it first sends a preflight OPTIONS request to ask the server which cross-origin requests are allowed. If the server does not respond to the OPTIONS request with appropriate Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers headers, the browser blocks the actual request entirely. From JavaScript, this appears as TypeError: Failed to fetch. The actual CORS error message appears in the browser console, but the JavaScript catch block only receives the TypeError.

Mixed content is a distinct cause that is frequently confused with CORS. When an HTTPS page fetches a resource from an HTTP URL, the browser blocks the request unconditionally regardless of CORS headers. This is a security policy that prevents HTTPS pages from loading potentially tampered content over unencrypted connections. The block happens at the network layer, producing TypeError: Failed to fetch, and the browser console shows a Mixed Content error. Switching the fetched URL from http:// to https:// resolves this, assuming the target server supports HTTPS.

In Node.js, the built-in fetch API became available in Node.js 18. Code that runs fetch() in Node.js 16 or earlier will throw TypeError: fetch is not a function, which is a different error than Failed to fetch. When using the built-in fetch in Node.js 18+, network failures produce TypeError: fetch failed with a cause property that contains the underlying error. Inspect err.cause to get the specific ECONNREFUSED, ETIMEDOUT, or ENOTFOUND error that explains why the connection failed.

Invalid URLs cause fetch to throw TypeError synchronously before any network request is made. A URL missing the protocol scheme, a relative URL passed to fetch in Node.js where there is no base URL, or a URL with invalid characters all cause an immediate throw. Check that the URL string is fully qualified with a scheme like https:// and does not contain unexpected undefined values substituted from template literals.

Chrome DevTools Network tab is the primary diagnostic tool for TypeError: Failed to fetch in browser applications. Open DevTools with F12, navigate to the Network tab, trigger the failing request, and look for red entries. A red entry marked failed indicates the browser could not complete the request. Click the entry to see the Request Headers, Response Headers, and Timing panels.

For CORS failures, look for two network entries: a preflight OPTIONS request and the actual request. If the OPTIONS request appears red, inspect its Response Headers for the Access-Control-Allow-Origin header. If the header is absent, the server is not configured to allow cross-origin requests from your origin. If only the actual request appears red and no OPTIONS request was made, the request may qualify as a simple request that did not trigger a preflight — check the browser console for the specific CORS error message.

The Timing panel in DevTools shows how far through the request lifecycle the browser got before failure. If the Stalled time is large and the connection shows no Waiting time, the browser could not even establish a TCP connection — suspect the server being down, a firewall blocking the port, or an incorrect hostname. If Stalled is small but the request still fails, the server accepted the connection but rejected it at the CORS preflight stage.

For Chrome specifically, the error code in the Network tab is valuable. ERR_CONNECTION_REFUSED means the server actively rejected the connection — the port is closed or nothing is listening. ERR_NAME_NOT_RESOLVED means DNS lookup failed — the hostname does not resolve. ERR_SSL_PROTOCOL_ERROR means a TLS handshake error. ERR_NETWORK_CHANGED means the network interface changed during the request, common on mobile devices switching between WiFi and cellular. Each of these requires a different fix.

For Node.js, add console.error(err.cause) to your catch block when using Node.js 18+ built-in fetch. The cause property contains the underlying network error from the operating system with a code property (ECONNREFUSED, ETIMEDOUT, ENOTFOUND) and an address property showing the IP address the connection was attempted to. This information is much more actionable than the top-level TypeError message alone. Test the same request with curl using the same URL and headers to verify whether the issue is in the Node.js fetch implementation or in the server.

CORS fixes must be applied on the server, not in the browser. The browser enforces CORS as a security policy and cannot be overridden by client-side code. The server must return the Access-Control-Allow-Origin header with either the specific origin (https://yourapp.com) or the wildcard * for public APIs. For requests that include credentials — cookies or HTTP authentication — the server must return Access-Control-Allow-Credentials: true and must specify the exact origin rather than a wildcard.

For preflight failures, ensure the server handles OPTIONS requests and returns the appropriate headers. In Express.js, use the cors middleware: app.use(cors({ origin: 'https://yourapp.com', credentials: true })). In other frameworks, configure the allowed methods, headers, and origins in the CORS configuration. The Access-Control-Allow-Methods header must include the actual HTTP method being used (GET, POST, PUT, etc.), and Access-Control-Allow-Headers must include any custom headers like Authorization or Content-Type.

Mixed content errors require updating the fetched URL to use HTTPS. If the target API does not support HTTPS, consider proxying the request through your own server, which can make the HTTP request from a secure server-to-server context and return the result to the browser over HTTPS. This eliminates mixed content blocking while keeping the communication between servers encrypted.

For development environments, a common pattern is to use a proxy configured in the development server. Create-React-App supports a proxy field in package.json. Vite supports a proxy configuration in vite.config.js. These development proxies forward requests from the browser to a different origin, bypassing CORS by making the request appear same-origin to the browser. This is a development-only solution and must be replaced with proper server-side CORS configuration for production.

For cookies across origins, set credentials: 'include' in the fetch options: fetch(url, { credentials: 'include' }). The server must respond with Access-Control-Allow-Credentials: true and must use a specific origin rather than wildcard * in Access-Control-Allow-Origin. Without both of these, the browser will not send cookies and the server will not accept them. Build and test requests in /tools/http-request-builder to verify headers are configured correctly before writing code.

The response.ok property is false for 4xx and 5xx responses, but fetch does not throw a TypeError for these. The error you receive in catch is only thrown when the network request itself fails. A common mistake is checking only for thrown errors and ignoring response.ok, resulting in code that silently passes error responses to res.json() and either fails with a JSON parse error when the error body is HTML, or returns an incorrect error object. Always check res.ok after every fetch call and throw explicitly based on it.

AbortController.abort() causes fetch to throw an AbortError, which is distinct from TypeError. The error name is 'AbortError' and the message is 'The user aborted a request.' AbortError should not trigger a retry because the abort was intentional. Check err.name === 'AbortError' before applying retry logic. A common bug is creating a new AbortController and calling abort() on it immediately after creating it, which aborts the request before it starts — check that abort is only called after a meaningful timeout or explicit user action.

navigator.onLine can report true even when actual network requests fail. The browser sets navigator.onLine to false only when the device has no network interface at all. A device connected to a WiFi network that has no internet access, or connected to a VPN that blocks certain routes, will show navigator.onLine === true while all fetch calls fail with TypeError. Use navigator.onLine as a quick hint, not as a definitive network check. The only reliable way to know whether a specific server is reachable is to make a request to it.

Service workers can intercept fetch requests and produce their own responses. If a service worker is registered and its fetch event handler throws or calls event.respondWith with a rejected promise, the browser delivers a TypeError: Failed to fetch to the original caller even if the server would have responded successfully. When debugging fetch failures in applications with service workers, temporarily disable the service worker in DevTools (Application tab, uncheck 'Bypass for network') to isolate whether the service worker is responsible.

Request body size limits on reverse proxies or load balancers cause connection resets that appear as TypeError: Failed to fetch. Nginx's client_max_body_size defaults to 1MB. AWS API Gateway has a 10MB payload limit. Cloudflare has a 100MB limit on its free tier. When uploading large files via fetch, check that all reverse proxies in the request path are configured to allow the expected body size. A connection reset mid-transfer appears as a TypeError because no HTTP response was received.

Assuming that every error from fetch is a network failure is the most common mistake. fetch throws TypeError for network failures, but it also throws TypeError for invalid URLs and SyntaxError for malformed JSON in res.json(). Code that catches all errors and treats them as network failures will misdiagnose URL bugs and JSON parsing errors as connectivity problems. Check the error name and message to distinguish the specific failure type before logging or displaying an error message.

Retrying on all TypeError exceptions without checking whether the failure is transient will create retry storms against servers that are intentionally rejecting requests. CORS rejections, mixed content blocks, and invalid URL errors will not resolve on retry. Only retry on errors that are likely transient: timeouts, connection refused for services that may be restarting, and network change errors on mobile. Add a retry count limit and exponential backoff to prevent tight retry loops from overwhelming a struggling service.

Sending fetch requests with credentials: 'include' without configuring the server to accept credentialed requests is a frequent CORS misconfiguration. When credentials are included, the server must return Access-Control-Allow-Credentials: true and must specify the exact origin rather than * in Access-Control-Allow-Origin. Browsers enforce both requirements strictly. A server that returns Access-Control-Allow-Origin: * with a credentialed request causes a CORS failure even though the wildcard seems permissive.

Ignoring the response body when handling error responses loses important diagnostic information. When a server returns a 4xx or 5xx response, the response body often contains a detailed error message, validation failure details, or a rate limit explanation. Code that only checks res.status and discards the body makes debugging production incidents much harder. Always await res.text() or res.json() for error responses and include the content in logs or error messages.

Failing to handle the case where fetch is not defined in older Node.js environments causes TypeError: fetch is not a function, which is a different error than the network failure TypeError. Add a runtime check or use the node-fetch package for Node.js 16 and earlier. In Node.js 18+, fetch is available globally without any import. In Node.js 20+, fetch is stable and recommended. Verify your Node.js version at the start of any fetch troubleshooting session to rule out the missing-fetch case.

Wrap all fetch calls in a centralized API client function rather than calling fetch directly throughout your codebase. The client function sets consistent defaults for timeout, headers, base URL, and error handling. All callers get the same behavior without duplicating error handling logic. When you need to change the timeout globally or add an authentication header, you update one place. This pattern also makes it straightforward to add request interceptors for logging, authentication token refresh, or telemetry.

Always pass an AbortController signal to long-running fetch calls. Create a controller with a timeout using setTimeout(() => controller.abort(), N). Cancel the timeout in a finally block if the request completes normally. Components that unmount before a fetch completes should call abort() on their component-level controller to prevent setState calls on unmounted components in React applications and to avoid processing stale responses that arrived after navigation.

Set explicit Content-Type headers when sending JSON request bodies. Without Content-Type: application/json, some servers may reject the request or attempt to parse the body as form data. Set Accept: application/json to communicate to the server that JSON is the expected response format. Some APIs respond with different content types based on Accept headers, and specifying JSON ensures consistent deserialization. Build and verify your request configuration in /tools/http-request-builder before implementing it in code.

Implement structured logging for all fetch failures that includes the request URL, method, error message, response status if available, and a request ID that correlates with server logs. Anonymous TypeError: Failed to fetch entries in production logs are nearly impossible to debug. A log entry with the URL, timestamp, and error code allows you to find the corresponding server log entry if one exists, or to identify patterns like a particular endpoint or user segment experiencing failures.

Test your CORS configuration with a real browser rather than curl. curl does not enforce CORS and will succeed on requests that browsers reject. Use the /tools/http-request-builder or a browser extension that makes cross-origin requests to verify that the server returns correct CORS headers before deploying. Automate CORS verification in your CI pipeline with a headless browser test that makes cross-origin requests from an HTTP server running locally on a different port, confirming that the CORS headers are present and correct in every deployment.