fetch API was only added in version 18. If you are running an older version, or if your environment lacks polyfills, the function does not exist. You can fix this by upgrading Node.js to version 18 or later, which includes native support for fetch without additional configuration.
Understanding the Environment Mismatch
The error message indicates that the JavaScript engine executing your code cannot locate thefetch function in the global scope. In modern web browsers, fetch is a standard API for making HTTP requests. However, in the Node.js runtime, this functionality was historically provided by third-party libraries like node-fetch or the built-in http module. The introduction of native fetch support changed this landscape significantly, creating a divergence between older and newer versions of the runtime.
If you are using Google's Gemini client library or any other modern framework that relies on fetch, it expects the environment to provide this global object automatically. When the runtime is too old, the library fails immediately upon import or initialization because the underlying dependency is missing. This is distinct from browser compatibility issues; it is purely a server-side versioning problem. Developers often encounter this when migrating legacy projects or working on shared CI/CD pipelines that default to older LTS (Long Term Support) versions.
Upgrading Node.js to Version 18+
The most robust solution is to ensure your development and production environments use Node.js version 18.0.0 or higher. Starting with version 18, Node.js ships with experimental support forfetch, which became stable in subsequent minor releases. This removes the need for external dependencies and aligns the server-side behavior with modern web standards.
To check your current version, run the following command in your terminal:
node -vv18.0.0, you should upgrade. You can use a version manager like nvm (Node Version Manager) to switch versions easily. For example:
nvm install 18
nvm use 18ReferenceError should disappear because the global fetch function is now available. Note that some very early v18 builds required a flag to enable fetch, but recent patch versions have it enabled by default. Always verify your specific minor version documentation if you encounter edge cases.
Installing Polyfills for Older Versions
If you are constrained to an older Node.js version due to legacy dependencies, you must manually provide thefetch functionality. The community standard for this is the node-fetch package. This library mimics the browser's fetch API, allowing your code to work identically regardless of the runtime version.
Install the package using npm:
npm install node-fetch@3node-fetch is fully compatible with ES modules and modern syntax. After installation, you need to make the function available globally or import it where needed. To make it global, add this line at the top of your entry point file:
import fetch from 'node-fetch';
global.fetch = fetch;fetch will find it. However, be aware that mixing global polyfills with native implementations can sometimes cause subtle bugs related to request handling or streaming. It is generally preferred to upgrade the runtime rather than rely on polyfills long-term.
Checking Package Dependencies
Sometimes the issue arises not from the Node.js version itself, but from how your project resolves dependencies. Ensure that yourpackage.json does not explicitly lock Node.js to an old version via engines fields that might confuse deployment tools. Additionally, clear your node_modules folder and reinstall dependencies after changing the Node.js version to avoid cached binaries or stale references.
rm -rf node_modules
npm installfetch, are resolved against the correct runtime capabilities. If you are using a framework that bundles its own server, such as Next.js or NestJS, check their specific requirements for Node.js versions. Some frameworks may require even newer versions than 18 to support the latest features of AI clients like Gemini.
For more information on resolving common Node.js response issues, see Postman Can't Get Response from Nodejs with Content-Length Over 1024.
Frequently Asked Questions
Does fetch work in all browsers?
Yes, fetch is supported in all modern browsers, including Chrome, Firefox, Safari, and Edge. It has replaced the older XMLHttpRequest API for most asynchronous operations. However, Internet Explorer does not support it natively, requiring polyfills for legacy compatibility.
Why did my code break after upgrading Node?
Upgrading Node.js changes the global scope and available APIs. If you were previously using a polyfill like node-fetch and assigned it to global.fetch, the native implementation might conflict or override it unexpectedly. Always test your application thoroughly after major version upgrades.
Can I use fetch with TypeScript?
Absolutely. TypeScript includes type definitions for fetch starting from lib DOM types. Ensure your tsconfig.json includes "dom" in the lib array if you are targeting both browser and Node environments. This provides proper autocomplete and type checking for fetch responses.
What is the alternative to fetch in older Node versions?
The built-in http and https modules are the standard alternatives. They provide lower-level control over requests but require more boilerplate code. Libraries like axios also offer a promise-based interface similar to fetch and work across all Node.js versions.
Is fetch faster than axios?
Native fetch is generally lighter weight because it is part of the core runtime, whereas axios adds bundle size. However, axios offers features like automatic JSON transformation and interceptor support out of the box, which can save development time despite the performance difference.