{"record":{"id":"6645f87dff0c9726","repo":"withastro/astro","slug":"cannotoptimizesvg","errorCode":"CannotOptimizeSvg","errorMessage":"An error occurred while optimizing SVG file \"${path}\" with the \"${name}\" optimizer.","messagePattern":"An error occurred while optimizing SVG file \"(.+?)\" with the \"(.+?)\" optimizer\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/svg/utils.ts","lineNumber":22,"sourceCode":"import { dropAttributes } from '../runtime.js';\nimport type { ImageMetadata } from '../types.js';\nimport type { SvgOptimizer } from './types.js';\n\nasync function parseSvg({\n\tpath,\n\tcontents,\n\tsvgOptimizer,\n}: {\n\tpath: string;\n\tcontents: string;\n\tsvgOptimizer: SvgOptimizer | undefined;\n}) {\n\tlet processedContents = contents;\n\tif (svgOptimizer) {\n\t\ttry {\n\t\t\tprocessedContents = await svgOptimizer.optimize(contents, path);\n\t\t} catch (cause) {\n\t\t\tthrow new AstroError(\n\t\t\t\t{\n\t\t\t\t\t...AstroErrorData.CannotOptimizeSvg,\n\t\t\t\t\tmessage: AstroErrorData.CannotOptimizeSvg.message(path, svgOptimizer.name),\n\t\t\t\t},\n\t\t\t\t{ cause },\n\t\t\t);\n\t\t}\n\t}\n\tconst root = parse(processedContents);\n\tconst svgNode = root.children.find(\n\t\t({ name, type }: { name: string; type: number }) => type === ELEMENT_NODE && name === 'svg',\n\t);\n\tif (!svgNode) {\n\t\tthrow new Error('SVG file does not contain an <svg> element');\n\t}\n\tconst { attributes, children } = svgNode;\n\tconst body = renderSync({ ...root, children });\n","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/withastro/astro/blob/157c500c38faa7ecf1251adbaeefcd109470d75c/packages/astro/src/assets/svg/utils.ts#L4-L40","documentation":"When Astro's SVG pipeline runs a configured optimizer (e.g. SVGO) over an SVG's contents and the optimizer throws, Astro wraps the failure as CannotOptimizeSvg with the original error attached as `cause` and includes the file path and optimizer name. The underlying optimizer error is the real problem; this error is the wrapper.","triggerScenarios":"Passing malformed SVG content through the SVG component/pipeline with an `svgOptimizer` configured; an SVGO plugin that chokes on the file (broken path data, invalid attributes, encoding issues); version drift between svgo v3 and v4 plugin APIs.","commonSituations":"Hand-edited SVGs with XML errors; SVGs exported from design tools containing unusual namespaces; adding a custom `svgoPlugins` config where a plugin name/API no longer matches the installed svgo major version.","solutions":["Inspect `error.cause` for the real optimizer message and fix the SVG at the reported location","Validate/pretty-print the SVG first (e.g. open in a browser, or run an XML linter) to confirm it is well-formed","Update or simplify the optimizer configuration: align svgo plugin names with your installed svgo major version, or remove the failing plugin"],"exampleFix":"// before (astro.config.mjs) — plugin API mismatch\nsvg: { optimizers: [{ name: 'svgo', options: { plugins: ['removeViewBox'] } }] }\n\n// after\nsvg: { optimizers: [{ name: 'svgo', options: { plugins: [{ name: 'preset-default' }] } }] }","handlingStrategy":"try-catch","validationCode":"// smoke-test the optimizer config once in CI against real assets\nimport { optimize } from 'svgo';\nfor (const svg of await glob('src/assets/**/*.svg')) {\n  optimize(await readFile(svg, 'utf8')); // throws early if config/plugins are bad\n}\nconsole.log('svg optimizer ok');","typeGuard":null,"tryCatchPattern":"try {\n  const node = await parseSvg({ path, contents, svgOptimizer });\n} catch (err) {\n  if (err instanceof AstroError && err.code === 'CannotOptimizeSvg') {\n    console.error(`optimizer ${err.cause} failed on ${path}:`, err.cause);\n    // retry without the optimizer, or skip optimizing this file\n    return parseSvg({ path, contents });\n  }\n  throw err;\n}","preventionTips":["Keep svgo plugin config aligned with the installed svgo major version","Run the optimizer over the whole asset folder in CI so bad SVGs fail before deploy","Always inspect error.cause — the wrapper message alone has no detail"],"tags":["astro","svg","svgo","optimization","cause-chaining"],"backgroundTag":"asset-optimization-failed","analyzedSha":"157c500c38faa7ecf1251adbaeefcd109470d75c","analyzedAt":"2026-08-27T22:42:12.133Z","contentChangedAt":"2026-08-27T22:42:12.133Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}