Node Fetch Proxy: Setup Guide with Code Examples 2026
Quick Takeaways
node-fetch does not automatically route requests through a proxy just because HTTP_PROXY or HTTPS_PROXY is set.
For node-fetch, the usual solution is to pass a custom proxy agent, such as https-proxy-agent, http-proxy-agent, or socks-proxy-agent.
For Node's native fetch, which is powered by Undici, the modern approach is to use Undici's ProxyAgent and pass it as a dispatcher.
Use HTTP/HTTPS proxies for most API and scraping requests. Use SOCKS5 proxies when you need broader protocol support or when your proxy provider gives SOCKS5 endpoints.
Nstproxy is a strong fit when your node-fetch proxy use case involves scraping, geo-targeted requests, ad verification, SEO monitoring, account workflows, or high-success-rate data access.
Lead-In
A common developer scenario looks like this: your script works locally, but fails on a company network, cloud server, scraping job, or geo-testing environment. The API call itself is simple. The hard part is getting fetch() to use the proxy correctly.
That confusion is exactly what the SERP shows. One top result is a GitHub issue about using Node fetch with proxies or agents. Another is a Stack Overflow question about configuring node-fetch behind a company proxy. In other words, users searching "node fetch proxy" are not asking whether proxies exist. They want working code.
The short answer: if you use node-fetch, pass a proxy agent through the option. If you use Node's built-in , use Undici's and .
node-fetch brings the Fetch API style to Node.js, but proxy handling is not the same as browser fetch.
In a browser, network routing is controlled by the browser or operating system. In Node.js, your script must explicitly tell the HTTP client how to connect. That is why a proxy setup usually requires an agent.
The target website sees the proxy IP instead of your server's original IP.
node-fetch vs Native Node fetch
Before writing code, check which fetch implementation you are using.
Fetch Type
Common Import
Proxy Setup Style
node-fetch package
import fetch from 'node-fetch'
Use agent
Node native fetch
Global fetch() in Node 18+
Use Undici dispatcher
Undici fetch
import { fetch } from 'undici'
Use Undici ProxyAgent with dispatcher
This distinction matters because agent and dispatcher are not interchangeable.
The official node-fetch README documents a custom agent option for networking-related behavior. Node's official docs explain that Undici powers the Fetch API in Node.js, and Undici's own docs show proxy usage through ProxyAgent.
How to Use an HTTP Proxy with node-fetch
For most proxy setups, start with https-proxy-agent. Even when the target URL is HTTPS, the proxy URL itself is often an HTTP proxy endpoint that supports HTTPS tunneling.
Nstproxy provides real proxy IPs for residential, ISP, datacenter, IPv6, unlimited residential, and mobile proxy use cases. For node-fetch, the integration logic is straightforward: generate a proxy endpoint in Nstproxy, then pass it into a proxy agent.
Example using an authenticated Nstproxy HTTP proxy:
This setup is useful when you want your Node.js requests to appear from a proxy IP instead of your server IP.
Why Choose Nstproxy for node-fetch Proxy Requests?
Nstproxy is a good fit for node-fetch users because proxy choice depends heavily on the request goal.
If you are fetching a normal public API from a company network, a simple HTTP proxy may be enough. But if you are scraping, testing localized pages, verifying ads, or monitoring prices, IP quality matters more.
Nstproxy's residential proxy page highlights real residential IPs across 190+ countries, country/city/ASN targeting, HTTP(S)/SOCKS5 support, customizable session time, and a 99.98% success rate. Its ISP proxy page highlights static ISP proxies with unlimited bandwidth, persistent sessions, and stability for long-duration tasks.
Best Nstproxy Product by Node Fetch Use Case
Use Case
Recommended Nstproxy Product
Why
Web scraping public pages
Residential proxies
Real-user IP trust and geo-targeting
Long API/session workflows
Static ISP proxies
Stable IP and persistent sessions
Low-risk high-speed requests
Datacenter proxies
Fast and cost-efficient
Large-scale IPv6-supported targets
IPv6 proxies
Scalable and affordable
Mobile-first testing
Mobile proxies
Carrier-style IP route
Heavy traffic with predictable usage
Unlimited residential proxies
Better for sustained volume
For most node-fetch proxy projects, start with Nstproxy Residential Proxies if the target blocks datacenter IPs or requires regional realism. Use Static ISP Proxies if your workflow needs one stable IP for a long session.
HTTP and HTTPS Targets in node-fetch
If your script fetches both HTTP and HTTPS URLs, you may want to return the right agent based on the target protocol.
If you use Nstproxy SOCKS5, generate a SOCKS5 proxy endpoint in your Nstproxy dashboard, then replace the proxy URL values.
Rotating Proxies with node-fetch
A rotating proxy changes the outgoing IP based on provider rules, session settings, or credentials. For scraping, SEO monitoring, ad verification, and geo-testing, this is often better than sending every request from one server IP.
A simple rotation setup can use one provider gateway:
If you need sticky sessions, configure the session behavior in your proxy provider settings. For Nstproxy, use residential proxies when you want rotating real-user IPs, and static ISP proxies when you want stable long sessions.
How to Use Proxy with Native Node fetch
If you are using Node 18+ global fetch, you are likely using Undici under the hood. In this case, use Undici's ProxyAgent.
Install Undici if your project imports it directly:
This avoids broken proxy URLs caused by special characters.
Error Handling and Retry Logic
Proxy requests fail for more reasons than normal requests. The proxy may be down, credentials may be wrong, the target may block the proxy IP, or the request may time out.
Use explicit timeouts, response checks, and controlled retries.
For scraping workflows, do not retry too aggressively. Repeated failed requests can make blocks worse.
Common node-fetch Proxy Problems
Problem
Likely Cause
Fix
FetchError: request to ... failed
Proxy connection failed
Check proxy host, port, and protocol
407 Proxy Authentication Required
Wrong or missing proxy credentials
Recheck username/password
ECONNRESET
Proxy or target closed connection
Add retries, lower concurrency, test another proxy
ETIMEDOUT
Proxy too slow or target unavailable
Use timeout and test proxy latency
Target still sees original IP
Agent not applied correctly
Confirm you passed agent or dispatcher
Works with curl but not fetch
Wrong agent type or URL encoding issue
Check HTTP vs HTTPS vs SOCKS agent
Too many CAPTCHAs
Low-quality or overused proxy IPs
Use residential or ISP proxies
node-fetch Proxy Best Practices
Use one agent per proxy configuration instead of recreating agents for every request unless you need per-request session changes.
Keep concurrency realistic. A good proxy cannot fix an overly aggressive scraper.
Use residential proxies for high-trust targets and datacenter proxies for low-risk speed.
Use static ISP proxies when the target expects a stable session.
Keep headers, cookies, and IP location consistent. If your proxy is in the US, avoid browser and request signals that look like a different region.
Monitor success rate, latency, block rate, and CAPTCHA frequency by proxy type.
FAQs
Does node-fetch support proxies?
node-fetch supports custom networking through the agent option. To use a proxy, pass an agent from packages such as https-proxy-agent, http-proxy-agent, or socks-proxy-agent.
Does node-fetch use HTTP_PROXY automatically?
In most setups, you should not assume node-fetch automatically uses HTTP_PROXY or HTTPS_PROXY. The reliable approach is to configure a proxy agent explicitly.
How do I use an HTTPS proxy with node-fetch?
Install https-proxy-agent, create a new HttpsProxyAgent with your proxy URL, and pass it to fetch() through the agent option.
How do I use a SOCKS5 proxy with node-fetch?
Install socks-proxy-agent, create a SocksProxyAgent with a socks5://username:password@host:port URL, and pass it as the agent.
What is the difference between agent and dispatcher?
node-fetch uses the agent option. Node's native fetch and Undici use dispatcher, usually with Undici's ProxyAgent.
Can I use Nstproxy with node-fetch?
Yes. Generate a proxy endpoint in Nstproxy, then use it with https-proxy-agent, socks-proxy-agent, or Undici ProxyAgent, depending on your fetch implementation and protocol.
Which Nstproxy proxy type is best for node-fetch?
Use residential proxies for scraping, SEO monitoring, ad verification, and geo-targeting. Use static ISP proxies for long sessions. Use datacenter or IPv6 proxies for fast low-risk requests.
Final Recommendation
If you are using node-fetch, use a proxy agent. If you are using Node's native fetch, use Undici's ProxyAgent with dispatcher.
For a quick test, https-proxy-agent is enough. For SOCKS5, use socks-proxy-agent. For production scraping, monitoring, or geo-testing, choose the proxy type carefully.
For most real-world node-fetch proxy workflows, Nstproxy Residential Proxies are the best starting point because they provide real-user IP trust, global targeting, HTTP(S)/SOCKS5 support, and session control. For long-running workflows, Nstproxy Static ISP Proxies are better because they provide stable IPs and persistent sessions.
The key is simple: the code connects the proxy, but proxy quality determines how well the request performs.
