{"record":{"id":"b4395ac197ec9b5b","repo":"withastro/astro","slug":"nomatchingimport","errorCode":"NoMatchingImport","errorMessage":"Could not render `${componentName}`. No matching import has been found for `${componentName}`.","messagePattern":"Could not render `(.+?)`\\. No matching import has been found for `(.+?)`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/runtime/server/hydration.ts","lineNumber":134,"sourceCode":"\ninterface HydrateScriptOptions {\n\trenderer: SSRLoadedRenderer;\n\tresult: SSRResult;\n\tastroId: string;\n\tprops: Record<string | number, any>;\n\tattrs: Record<string, string> | undefined;\n}\n\n/** For hydrated components, generate a <script type=\"module\"> to load the component */\nexport async function generateHydrateScript(\n\tscriptOptions: HydrateScriptOptions,\n\tmetadata: Required<AstroComponentMetadata>,\n): Promise<SSRElement> {\n\tconst { renderer, result, astroId, props, attrs } = scriptOptions;\n\tconst { hydrate, componentUrl, componentExport } = metadata;\n\n\tif (!componentExport.value) {\n\t\tthrow new AstroError({\n\t\t\t...AstroErrorData.NoMatchingImport,\n\t\t\tmessage: AstroErrorData.NoMatchingImport.message(metadata.displayName),\n\t\t});\n\t}\n\n\tconst island: SSRElement = {\n\t\tchildren: '',\n\t\tprops: {\n\t\t\t// This is for HMR, probably can avoid it in prod\n\t\t\tuid: astroId,\n\t\t},\n\t};\n\n\t// Attach renderer-provided attributes\n\tif (attrs) {\n\t\tfor (const [key, value] of Object.entries(attrs)) {\n\t\t\tisland.props[key] = escapeHTML(value);\n\t\t}","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/runtime/server/hydration.ts#L116-L152","documentation":"To generate the hydration script, Astro needs to know which export of the component module to load in the browser (metadata.componentExport.value, filled in during compile-time import analysis). If that value is empty, the component's import could not be statically analyzed, and generateHydrateScript throws NoMatchingImport for the component's display name.","triggerScenarios":"Applying client:* to a component reached through dynamic import (import(`./widgets/${name}.jsx`)), import * as barrels that re-export framework components, virtual modules from custom plugins, or re-export chains the compiler cannot trace back to a real file export.","commonSituations":"Component registries built with dynamic imports; index.ts barrel files re-exporting hydrated components; custom Vite plugins serving framework components from virtual paths; refactors that moved hydrated components behind indirection.","solutions":["Import the hydrated component directly with a static import in the .astro file that renders it","Give the component module a plain default export and hydrate that","Remove indirection (dynamic import, spread re-export, virtual module) between the .astro file and the component file","Keep client:* usage in the same module that performs the static import"],"exampleFix":"// before\nconst Widget = await import(`../widgets/${name}.jsx`);\n<Widget client:load />\n\n// after\nimport Widget from '../widgets/Widget.jsx';\n<Widget client:load />","handlingStrategy":"validation","validationCode":"// dev-time sanity check: hydrated components must resolve to a real export\nconst mod = await import(componentUrl);\nif (!(componentExportName in mod)) {\n  throw new Error('Export ' + componentExportName + ' missing — client:* requires a statically analyzable import');\n}","typeGuard":"function hasExport(mod: Record<string, unknown>, name: string): boolean {\n  return name === 'default' ? 'default' in mod : Object.hasOwn(mod, name);\n}","tryCatchPattern":null,"preventionTips":["Use static imports for every component that gets a client:* directive","Give hydrated components a default export","Avoid dynamic import(), import * as barrels, and virtual modules between the .astro file and hydrated components"],"tags":["astro","hydration","import-analysis","compiler"],"backgroundTag":"unresolvable-module-export","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"}