{"record":{"id":"54c2792129d833be","repo":"withastro/astro","slug":"getimagenotusedonserver","errorCode":"GetImageNotUsedOnServer","errorMessage":"`getImage()` should only be used on the server. To use images on the client, render the `src` from `getImage()` during the server render, then pass it to the client for usage.","messagePattern":"`getImage\\(\\)` should only be used on the server\\. To use images on the client, render the `src` from `getImage\\(\\)` during the server render, then pass it to the client for usage\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/vite-plugin-assets.ts","lineNumber":189,"sourceCode":"\t\t\t\t},\n\t\t\t},\n\t\t\tload: {\n\t\t\t\tfilter: {\n\t\t\t\t\tid: new RegExp(`^(${RESOLVED_VIRTUAL_MODULE_ID}|${RESOLVED_VIRTUAL_GET_IMAGE_ID})$`),\n\t\t\t\t},\n\t\t\t\thandler(id) {\n\t\t\t\t\tif (id === RESOLVED_VIRTUAL_GET_IMAGE_ID) {\n\t\t\t\t\t\t// Lightweight module exporting only getImage + imageConfig.\n\t\t\t\t\t\t// No component references (Image, Picture, Font) to avoid TDZ\n\t\t\t\t\t\t// errors when the content runtime and component pages are\n\t\t\t\t\t\t// bundled into the same prerender chunk (see #16036).\n\t\t\t\t\t\tconst isServerEnvironment = isAstroServerEnvironment(this.environment);\n\t\t\t\t\t\tconst getImageExport = isServerEnvironment\n\t\t\t\t\t\t\t? `import { getImage as getImageInternal } from \"astro/assets\";\n\t\t\t\t\t\t\t\texport const getImage = async (options) => await getImageInternal(options, imageConfig);`\n\t\t\t\t\t\t\t: `import { AstroError, AstroErrorData } from \"astro/errors\";\n\t\t\t\t\t\t\t\texport const getImage = async () => {\n\t\t\t\t\t\t\t\t\tthrow new AstroError(\n\t\t\t\t\t\t\t\t\t\tAstroErrorData.GetImageNotUsedOnServer.message,\n\t\t\t\t\t\t\t\t\t\tAstroErrorData.GetImageNotUsedOnServer.hint,\n\t\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\t};`;\n\n\t\t\t\t\t\tconst assetQueryParams = settings.adapter?.client?.assetQueryParams\n\t\t\t\t\t\t\t? `new URLSearchParams(${JSON.stringify(\n\t\t\t\t\t\t\t\t\tArray.from(settings.adapter.client.assetQueryParams.entries()),\n\t\t\t\t\t\t\t\t)})`\n\t\t\t\t\t\t\t: 'undefined';\n\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcode: `\n\t\t\t\t\t\t\t\texport const imageConfig = ${JSON.stringify(settings.config.image)};\n\t\t\t\t\t\t\t\tObject.defineProperty(imageConfig, 'assetQueryParams', {\n\t\t\t\t\t\t\t\t\tvalue: ${assetQueryParams},\n\t\t\t\t\t\t\t\t\tenumerable: false,\n\t\t\t\t\t\t\t\t\tconfigurable: true,","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/assets/vite-plugin-assets.ts#L171-L207","documentation":"The Vite virtual module for `astro:assets` getImage generates two variants based on the Vite environment. When the importing module is in a client environment (isAstroServerEnvironment is false), the emitted `getImage` is a stub that throws GetImageNotUsedOnServer on call. This variant is the RESOLVED_VIRTUAL_GET_IMAGE_ID handler — the lightweight getImage-only export.","triggerScenarios":"Importing `getImage` from astro:assets (or the resolved virtual id) inside a module that Vite compiles for the client environment, then calling it at runtime. The client build replaces getImage with a thrower; calling it produces this error.","commonSituations":"Calling getImage() inside a `<script>` (client) or a framework client component; importing astro:assets getImage from a .client.ts island; rendering pipeline mis-classifying a module as client due to environment misconfiguration; using getImage in an event handler.","solutions":["Call getImage() during server render (frontmatter / .server modules / getStaticPaths) and pass the resulting src to the client.","Pass the optimized src into client code via `define:vars` or a data attribute, not by calling getImage on the client.","For pure client-side images, use a plain <img> tag instead of getImage.","Confirm the module is not accidentally marked client-only (check import paths and Vite environment assignment)."],"exampleFix":"---\nimport { getImage } from 'astro:assets';\nimport logo from '../assets/logo.png';\nconst img = await getImage({ src: logo, width: 200 }); // server\n---\n<script define:vars={{ imgSrc: img.src }}>\n  document.getElementById('logo').src = imgSrc; // client uses string\n</script>","handlingStrategy":"type-guard","validationCode":"// never call getImage in client code; gate calls\nif (import.meta.env.SSR) {\n  const img = await getImage({ src });\n}","typeGuard":"const isServer = typeof import.meta !== 'undefined' && (import.meta as any).env?.SSR === true;","tryCatchPattern":null,"preventionTips":["Keep getImage imports in .server.ts or frontmatter only.","Pass resolved src strings to client islands, not the getImage function.","Use a linter rule (e.g. eslint no-restricted-imports) to forbid astro:assets in client files."],"tags":["assets","getimage","ssr","client-server"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}