{"record":{"id":"ad7ed1acf377ef5e","repo":"withastro/astro","slug":"serveronlymodule-ad7ed1","errorCode":"ServerOnlyModule","errorMessage":"The \"astro:env/server\" module is only available server-side.","messagePattern":"The \"astro:env/server\" module is only available server-side\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/env/vite-plugin-env.ts","lineNumber":86,"sourceCode":"\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\tload: {\n\t\t\tfilter: {\n\t\t\t\tid: new RegExp(\n\t\t\t\t\t`^(${RESOLVED_CLIENT_VIRTUAL_MODULE_ID}|${RESOLVED_SERVER_VIRTUAL_MODULE_ID}|${RESOLVED_INTERNAL_VIRTUAL_MODULE_ID})$`,\n\t\t\t\t),\n\t\t\t},\n\t\t\thandler(id) {\n\t\t\t\tif (id === RESOLVED_INTERNAL_VIRTUAL_MODULE_ID) {\n\t\t\t\t\treturn { code: `export const schema = ${JSON.stringify(schema)};` };\n\t\t\t\t}\n\n\t\t\t\tif (\n\t\t\t\t\tid === RESOLVED_SERVER_VIRTUAL_MODULE_ID &&\n\t\t\t\t\tisAstroClientEnvironment(this.environment)\n\t\t\t\t) {\n\t\t\t\t\tthrow new AstroError({\n\t\t\t\t\t\t...AstroErrorData.ServerOnlyModule,\n\t\t\t\t\t\tmessage: AstroErrorData.ServerOnlyModule.message(SERVER_VIRTUAL_MODULE_ID),\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\tif (id === RESOLVED_CLIENT_VIRTUAL_MODULE_ID || id === RESOLVED_SERVER_VIRTUAL_MODULE_ID) {\n\t\t\t\t\tconst loadedEnv = envLoader.get();\n\n\t\t\t\t\tconst validatedVariables = validatePublicVariables({\n\t\t\t\t\t\tschema,\n\t\t\t\t\t\tloadedEnv,\n\t\t\t\t\t\tvalidateSecrets,\n\t\t\t\t\t\tsync,\n\t\t\t\t\t});\n\t\t\t\t\tconst { client, server } = getTemplates({\n\t\t\t\t\t\tschema,\n\t\t\t\t\t\tvalidatedVariables,\n\t\t\t\t\t\t// In dev, we inline process.env to avoid freezing it","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/env/vite-plugin-env.ts#L68-L104","documentation":"The virtual module `astro:env/server` provides server-only (secret) environment variables and exists only in the server environment. Astro's env Vite plugin throws ServerOnlyModule when that module is resolved from a client environment - meaning you imported it, directly or transitively, into code that ships to the browser.","triggerScenarios":"importing `astro:env/server` in a file bundled for the client: an inline `<script>` tag, a framework component with a `client:*` directive, or a shared utility imported by both server endpoints and client code.","commonSituations":"Centralizing env access in a shared lib/env.ts imported everywhere; refactoring a helper that reads a secret into a file also reachable from the browser; converting an SSR page to static and having its formerly server-only imports become part of the client graph.","solutions":["In client-reachable code, import from `astro:env/client` instead - secret values can never be exposed to the browser by design.","Split shared modules: keep secret reads in files imported only by server code (endpoints, middleware, server components).","If a `client:*` component needs configuration, pass it as props from the server rather than importing astro:env/server inside the component."],"exampleFix":"// before - module bundled for the client\nimport { SECRET_API_KEY } from 'astro:env/server';\n\n// after - public value via the client module, secrets passed as props\nimport { PUBLIC_API_URL } from 'astro:env/client';","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"// in shared code that must never pull server env into the client graph\nfunction assertServerEnv(): void {\n  if (!import.meta.env.SSR) {\n    throw new Error('this module reads astro:env/server and must not be bundled for the client');\n  }\n}","tryCatchPattern":null,"preventionTips":["Name server-only env modules clearly (env.server.ts) and lint against importing them from client entry points.","Never import astro:env/server from files reachable via client:* components or inline <script> tags.","Use astro:env/client for browser-visible values; secrets stay behind the server boundary by design."],"tags":["environment-variables","server-only","vite","bundling"],"backgroundTag":"server-only-module-import","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}