Skip to main content

Known Restrictions

You can use Walrus Sites to deploy almost any form of traditional static Web2 website built for modern browsers. There are, however, a number of restrictions to keep in mind when you create or port a website to Walrus Sites.

Can Walrus Sites run server-side code?​

Walrus Sites store all site resources (HTML, CSS, JS, images, fonts) as blobs on Walrus, and a Sui smart contract manages their metadata. There is no server-side runtime. As a consequence:

  • No server-side rendering (SSR): Frameworks that require a Node.js (or equivalent) server to render pages per request (such as Next.js in SSR mode, Nuxt.js, or Remix) cannot run their server component on Walrus Sites. You can deploy only the pre-built static output of those frameworks (that is, exported HTML, CSS, and JS).
  • No server-side logic: There are no endpoints, no request handlers, and no databases. You must implement operations that a backend normally handles (such as form processing, authentication sessions, or database queries) using client-side code integrated with external APIs or Sui smart contracts.
  • No runtime redirects: Redirect plugins that execute at serve time (for example, the Docusaurus redirect plugin that routes /old-path to /new-path at the server level) do not function as expected. Use client-side redirect workarounds instead. See Redirects for supported approaches.

Can a site store secret values?​

All content stored on Walrus Sites is fully public. Walrus stores site files as blobs, and Sui stores site metadata. Because there is no private execution environment, you must not embed secret values anywhere in a site's source files. This includes:

  • API keys or tokens
  • Private keys or wallet seeds
  • Passwords or credentials
  • Environment variables intended to be private

Handle any backend-specific operations that require secrets (such as authentication flows or privileged API calls) through integration with Sui smart contracts and a Sui-compatible wallet, keeping secrets out of the deployed site assets entirely.

What is the maximum redirect depth?​

The portal caps the number of consecutive redirects a Walrus Site can perform. This prevents infinite redirect loops during site loading.

  • The public portal at https://wal.app enforces a maximum redirect depth of 3.
  • Other portals might configure this limit differently. Self-hosted portals can adjust the value as needed.

Redirect chains deeper than the portal's limit result in the site failing to load.

Routing constraints in ws-resources.json​

The ws-resources.json configuration file controls client-side routing, custom headers, and site metadata. It has several notable constraints:

  • Wildcard position is fixed: Route wildcards (*) can only appear at the end of a path pattern. /path/* is valid; /path/*/to and */path/* are not.
  • Route targets must exist: Every route value must reference a resource that actually exists among the site's deployed files. The Walrus Sites smart contract aborts if you define a route pointing to a non-existent resource.
  • No server-side redirect support: The routes section implements client-side routing rules only. Framework-level redirect plugins that run server-side at request time do not function as expected.
  • Header scope is per-resource: Custom HTTP headers defined in the headers section apply to individual resource paths, not globally. You must explicitly configure each path that needs custom headers.

Service-worker portal limitations​

The following restrictions apply only to portals based on service workers (such as a self-hosted instance of the worker portal from the walrus-sites repository). If you need any of these features, use a server-side portal instead.

Service-worker portals cannot serve sites that use service workers​

A service-worker portal installs its own service worker in the browser to resolve site metadata from Sui and fetch content from Walrus. Because browsers allow only one service worker per origin, a Walrus Site accessed through a service-worker portal cannot register its own service worker. Attempting to install a site-level service worker from within such a portal results in a broken site experience for the user.

iOS Sui mobile wallet compatibility​

A limitation of the WebKit engine prevents in-app browsers on iOS from loading service workers. As a result:

  • You cannot use Walrus Sites accessed through a service-worker portal within Sui-compatible wallet apps on iOS.
  • This means iOS wallet users cannot interact with onchain features (wallet connection, transaction signing) from within a service-worker portal.
  • Browsing a Walrus Site on iOS through a standard browser (Safari, Chrome, and so on) still works correctly.

Recommended mitigation: If you use a service-worker portal as your primary access point, redirect iOS wallet users to a server-side portal (for example, https://wal.app). This allows the wallet interaction to function correctly through the <site_name>.wal.app server-side endpoint.

Are progressive web apps supported?​

Service-worker portals are fundamentally incompatible with progressive web apps (PWA) due to two structural conflicts:

  1. The portal must register its own service worker for the site to work at all. This prevents the browser from loading the PWA manifest correctly.
  2. There can only be one service worker registered per origin. Registering a PWA's service worker would overwrite the portal's service worker, breaking the site entirely.

The server-side portal does not share these limitations: these PWA conflicts apply only to portals based on service workers. If your site must remain usable through a service-worker portal, avoid PWA features; otherwise, serve the site through a server-side portal (for example, https://wal.app), where PWA service workers are not in conflict with the portal.

Domain and naming constraints​

  • SuiNS dependency for human-readable URLs: Without a SuiNS name, a site is only accessible through a Base36-encoded Sui object ID subdomain (for example, 58gr4pinoayuijgdixud23441t55jd94ugep68fsm72b8mwmq2.wal.app). This is because subdomains are case-insensitive (ruling out Base64 and Base58) and limited to 63 characters (ruling out hex, which requires 64).
  • No traditional DNS control: Walrus Sites do not support custom DNS records or traditional domain name configuration. SuiNS exclusively manages human-readable names.
  • Subdomain isolation required: You must access each site through a unique subdomain of the portal domain to ensure security isolation between sites and correct wallet connection behavior in the browser. Walrus Sites do not support shared-origin access.