Why Is the ipfs.io Gateway Not Working?

If your application relies on ipfs.io or dweb.link to load images, retrieve metadata, or download files, it’s time to move that traffic to infrastructure built for your workload.

The IPFS project is retiring the sponsored gateways’ traditional role as shared HTTP retrieval services. Browser visits are transitioning to a service worker gateway, while hot-linked assets and backend requests face increasing rate limits. The official migration announcement names Filebase among the commercial pinning and retrieval providers available to developers.

At Filebase, we help you maintain gateway continuity: keep your existing IPFS content identifiers, serve your application through a dedicated HTTPS endpoint, and use a domain your business controls.

What is happening to ipfs.io and dweb.link?

Historically, a public gateway handled IPFS retrieval on your behalf. Your application requested a URL containing a content identifier, or CID, and the gateway retrieved the content and returned an ordinary HTTP response.

That familiar model made it easy to add IPFS to websites and applications. It also made a handful of free endpoints critical dependencies for production systems.

The transition changes how those endpoints work. Direct browser navigation is being redirected to inbrowser.link, where retrieval happens through a service worker. Shipyard announced the browser redirect rollout in May 2026, alongside plans for additional restrictions on other traffic.

Our recommendation is to migrate production traffic now. An endpoint that still answers some requests today is already an unreliable foundation for a customer-facing application.

How the service worker model works

A service worker is JavaScript that runs in the browser and can intercept network requests. The IPFS service worker gateway uses Helia and verified retrieval to fetch content-addressed blocks, check them against their CIDs, and assemble the content locally. It can retrieve from peers using browser-compatible connections or from HTTP sources that provide verifiable blocks. The project documentation explains the architecture.

This gives browser users a way to verify content themselves and retrieve it from multiple sources. They do not need to install a separate IPFS application or browser extension. At inbrowser.link, each CID receives its own subdomain to preserve browser origin isolation. Read the rollout details.

However, a browser-based retrieval experience does not replace every HTTP integration. A backend job, command-line client, or native application making an HTTP request does not automatically run the service worker. Likewise, embedding an image from another domain does not install that domain’s service worker into your application.

The practical consequence: a link may open successfully in a browser tab while the application consuming it still fails. Test the actual request path your users depend on.

Choose a retrieval path that fits your application

For projects that need ordinary HTTP responses, there are two main options: operate a gateway yourself or use a managed gateway.

Self-hosting gives your team control over deployment and capacity. IPFS recommends Rainbow for retrieval-focused workloads and Kubo when you also need to publish content. Browser applications can instead integrate @helia/verified-fetch or a service worker, with production routing and retrieval endpoints configured explicitly. The IPFS migration guide covers these options.

If you self-host, plan for more than starting a process. Your operating plan should cover:

• Capacity and uptime: peak traffic, caching, bandwidth, monitoring, and recovery from failures.
• Reliable retrieval: provider discovery, healthy peer connections, and peering arrangements where useful.
• Content moderation: policies, deny lists, and procedures for handling prohibited content served through your domain.
• Abuse prevention: controls that prevent unrelated users from consuming your gateway’s resources.

A managed gateway is useful when your team wants to keep its existing HTTP delivery model and have a provider operate the retrieval infrastructure.

Maintain gateway continuity with Filebase

Our Dedicated IPFS Gateways give your project its own endpoint for retrieving IPFS content over HTTPS. Your website, backend, mobile application, or integration can request files through that endpoint without requiring a service worker.

We combine managed retrieval infrastructure with a global CDN and edge caching across North America, Europe, and Asia. You can connect a custom domain, and we handle its TLS certificate provisioning and renewal. Explore our gateway infrastructure.

You also get tools for operating the service around your application:

• Gateway activity streams: inspect requested CIDs, response statuses, and response sizes to investigate delivery issues. Activity stream documentation.
• Image optimization: resize, compress, and convert supported images through URL parameters, with transformed responses cached for subsequent requests. Image optimization documentation.
• Access controls: restrict which content your gateway serves and configure additional authentication where appropriate. These controls help prevent your endpoint from becoming a delivery service for arbitrary third-party content. Access control documentation.
• Infrastructure protection: DDoS protection and threat monitoring support the delivery layer. Gateway features.

For production, provision a dedicated gateway in your account. Our shared public gateway is intended for testing and light usage. Choose capacity around your expected storage and transfer needs; IPFS outbound bandwidth is billable under your plan. IPFS bandwidth documentation.

How to migrate your application

1. Find every dependency on the public gateways

Search application code, configuration, databases, SDK defaults, and generated metadata for ipfs.io and dweb.link.

Check nested references too. Moving the gateway used to fetch a JSON document will not fix an image URL inside that document that still points to ipfs.io.

Include background workers, integrations, mobile clients, and fallback settings in your review. A migration is incomplete if an error path silently returns to the retiring endpoints.

2. Pin the content your project depends on

Gateway access and content persistence serve different purposes. For your own production assets, pin the existing CIDs to Filebase before switching delivery.

Our IPFS Pinning Service API lets you request pins for existing content and check their status. Wait until each required pin reaches pinned, and verify that the content can be retrieved. Keep the original provider or source node available during this process.

Re-pinning an existing CID preserves its content identity. If you recreate the content through a fresh upload, differences in import settings or directory structure can produce a different CID. Where exact preservation matters, use the existing CID or import its original DAG through a CAR archive; our IPFS RPC API supports CAR imports.

3. Create a dedicated gateway and connect your domain

In the Filebase console, open Gateways, create a gateway, and choose the content access mode appropriate for your application. Its default address follows this pattern:

https://<gateway-name>.myfilebase.com/ipfs/<CID>

Follow our dedicated gateway setup guide, then add a domain such as ipfs.yourcompany.com. Use the CNAME target shown in the console and wait for domain verification and certificate provisioning. Custom domain instructions.

A domain you control gives your application a stable delivery address. Future infrastructure changes can happen behind that address, provided the replacement preserves the required paths and behavior.

4. Update retrieval URLs while preserving CIDs and paths

For an ordinary path-style gateway request, the migration looks like this:

Replace the example hostname with your configured domain. Preserve the CID, file path, and relevant query parameters.

Centralize URL resolution in your application so it can handle raw CIDs, ipfs:// references, and recognized gateway URL formats consistently. Subdomain-style URLs require parsing the CID from the hostname; a simple text replacement will not cover every format.

For on-chain references stored as ipfs://<CID>, your application can select a different HTTP gateway without changing the content identifier. A literal ipfs.io URL stored in immutable data needs special handling by the consuming application; changing your gateway configuration cannot rewrite that stored value.

5. Validate delivery before completing the switch

Test representative images, JSON, downloads, directory paths, and any IPNS usage from your real clients. Check CORS, content types, redirects, authentication, and range requests where your application needs them.

Monitor errors, latency, and bandwidth as you move traffic. Retain a working rollback path during the transition and remove the retired public endpoints from production fallback lists.

If your publishing workflow also needs migration, we support the IPFS Pinning Service API, S3-compatible uploads to IPFS buckets, and a documented subset of the Kubo HTTP RPC API. Review our IPFS integration options.

A sustainable next step for IPFS

Free public gateways helped make IPFS accessible. Over time, production applications concentrated traffic on endpoints whose operators subsidized retrieval for the broader ecosystem.

The IPFS project is now directing resources toward interoperability, specifications, conformance tests, and maintainers, while retrieval moves toward browser clients and independently operated infrastructure. The protocol continues to support content verification and portability between providers. Read the project’s explanation.

We see gateway continuity as a practical part of that transition. Keep your content pinned, retain its CIDs, and deliver it through an endpoint your business can configure and monitor.

Ready to move your production traffic? Create a Filebase account and set up a Dedicated IPFS Gateway. For help planning a migration, contact us at hello@filebase.com with your current gateway usage, content volume, and expected traffic.