{"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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/env/vite-plugin-env.ts#L68-L104","documentation":"The virtual module `astro:env/server` resolves server-only validated environment variables and must never ship to the browser. When Vite's plugin handler is asked to load it from inside the Astro client environment (`isAstroClientEnvironment`), Astro throws `ServerOnlyModule` to prevent server secrets from being bundled into client code.","triggerScenarios":"Importing `astro:env/server` (directly or transitively) in code that Vite resolves under the Astro client environment — e.g. a component rendered on the client, a `<script>` block, or a client directive entrypoint that pulls in server env values.","commonSituations":"Accidentally importing the server env module in a shared utility that is also imported by client-side code; importing `astro:env/server` in a `.astro` component's frontmatter that is also evaluated for client rendering; a barrel file (`index.ts`) re-exporting both client and server env modules.","solutions":["Remove the `astro:env/server` import from any module reachable by client-side code; keep server env usage in server-only entrypoints (endpoints, middleware, server islands).","Split shared utilities so server-only imports live in a separate file the browser never imports.","If the value is needed client-side, declare it in `env.schema` with `access: 'public'` and import it from `astro:env/client` instead.","Trace the import chain (Vite's error or `vite build --debug`) to find which client entrypoint pulls in the server module."],"exampleFix":"// before — shared util imported by both server and client\nimport { DATABASE_URL } from 'astro:env/server';\nexport function dbUrl() { return DATABASE_URL; }\n\n// after — server util is server-only; client gets nothing from this path\n// server.ts (never imported by client code)\nimport { DATABASE_URL } from 'astro:env/server';\nexport function dbUrl() { return DATABASE_URL; }","handlingStrategy":"validation","validationCode":"import { isServer } from 'astro';\n// Gate server-env imports behind a server check, or better: keep them in server-only files.\n// Static-analysis alternative: ensure 'astro:env/server' only appears in files under /server or endpoints.","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Keep server-env imports in files only endpoints/middleware import.","Avoid barrel files that re-export astro:env/server.","Run `astro check` and review the client bundle for server module leakage."],"tags":["security","env","vite","bundling","secrets"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}