{"record":{"id":"321f26c102fdf298","repo":"remix-run/react-router","slug":"you-cannot-use-router-method-on-the-server-be","errorCode":null,"errorMessage":"You cannot use router.${method}() on the server because it is a stateless environment","messagePattern":"You cannot use router\\.(.+?)\\(\\) on the server because it is a stateless environment","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/react-router/lib/dom/server.tsx","lineNumber":447,"sourceCode":"        revalidation: \"idle\" as RevalidationState,\n        fetchers: new Map(),\n        blockers: new Map(),\n      };\n    },\n    get routes() {\n      return dataRoutes;\n    },\n    get manifest() {\n      return manifest;\n    },\n    get window() {\n      return undefined;\n    },\n    match(locationArg) {\n      return matchRoutes(locationArg)?.map(mapRouteMatch) ?? null;\n    },\n    initialize() {\n      throw msg(\"initialize\");\n    },\n    subscribe() {\n      throw msg(\"subscribe\");\n    },\n    enableScrollRestoration() {\n      throw msg(\"enableScrollRestoration\");\n    },\n    navigate() {\n      throw msg(\"navigate\");\n    },\n    fetch() {\n      throw msg(\"fetch\");\n    },\n    revalidate() {\n      throw msg(\"revalidate\");\n    },\n    createHref,\n    encodeLocation,","sourceCodeStart":429,"sourceCodeEnd":465,"githubUrl":"https://github.com/remix-run/react-router/blob/7aea711dd1ae2bc5a076d13ff17291829690fa74/packages/react-router/lib/dom/server.tsx#L429-L465","documentation":"createStaticRouter() (packages/react-router/lib/dom/server.tsx) returns a stateless server-side stub of the router API for SSR. It only supports reading state (state, routes, match, etc.); mutation/subscription methods like initialize(), subscribe(), navigate(), fetch(), and enableScrollRestoration() throw this error because a server request has no persistent browser session or history to track. The library throws it to fail fast when client-only router APIs are invoked during server rendering.","triggerScenarios":"Calling router.initialize(), router.subscribe(), router.navigate(), router.fetch(), router.revalidate(), router.deleteFetcher(), router.enableScrollRestoration(), or any other mutating/subscription method on the router object returned by createStaticRouter() during SSR. Typically happens when code shared between client and server calls these methods without checking the environment, or when a static router handle leaks into server-side code.","commonSituations":"Calling router.initialize() manually in a custom entry point (entry.server.tsx) after createStaticRouter(); subscribing to router state changes in shared components/utilities rendered on the server; attempting fetcher calls (router.fetch()) or navigation during SSR; reusing a router-usage pattern from client-side createBrowserRouter in server rendering code.","solutions":["Remove the call to router.initialize()/subscribe()/etc. from server-side code paths; the static router state is already fully initialized from the loader run — pass `router.state` to <StaticRouterProvider> instead.","Guard environment: only call mutating router APIs when `typeof document !== 'undefined'` (or via the RouterProvider on the client), and skip them during SSR.","For custom SSR entry points, use the documented flow: createStaticRouter() + createStaticHandler() + <StaticRouterProvider router={router} context={context}>, without manually initializing or subscribing.","If you need server-side data loading, call staticHandler.query()/queryRoute() rather than router.navigate()/fetch()."],"exampleFix":"// before (entry.server.tsx)\nconst router = createStaticRouter(routes, context);\nrouter.initialize(); // throws on the server\n\n// after\nconst router = createStaticRouter(routes, context);\nconst contextValue = getStaticContextFromError(router, context, ...);\nreturn <StaticRouterProvider router={router} context={contextValue} nonce={nonce} />;","handlingStrategy":"validation","validationCode":"const isServer = typeof document === 'undefined';\nif (!isServer) {\n  router.initialize();\n}","typeGuard":"function isClientRouter(router: Router): boolean {\n  return typeof document !== 'undefined' && typeof router.initialize === 'function';\n}","tryCatchPattern":"try {\n  router.initialize();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('stateless environment')) {\n    // SSR: skip client-only router mutation; state is already populated\n  } else {\n    throw e;\n  }\n}","preventionTips":["Never call router.initialize(), subscribe(), navigate(), or fetch() in code executed during SSR (entry.server.tsx, loaders, server-rendered components).","Rely on <StaticRouterProvider> to hydrate server state; do not manually initialize a static router.","Add an environment check (`typeof document !== 'undefined'`) around any shared client/server code that mutates router state.","Keep client-only router logic inside effects/event handlers so it never runs during server render."],"tags":["ssr","router","stateless-environment","react-router"],"backgroundTag":"unsupported-operation","analyzedSha":"7aea711dd1ae2bc5a076d13ff17291829690fa74","analyzedAt":"2026-09-08T10:38:21.030Z","contentChangedAt":"2026-09-08T10:38:21.030Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}