{"record":{"id":"072878b125836280","repo":"withastro/astro","slug":"you-are-attempting-to-render-tagname-clienta","errorCode":null,"errorMessage":"You are attempting to render <${tagName} ${clientAttr} />, but ${tagName} is an Astro component. Astro components do not render in the client and should not have a hydration directive. Please use a framework component for client rendering.","messagePattern":"You are attempting to render <(.+?) (.+?) />, but (.+?) is an Astro component\\. Astro components do not render in the client and should not have a hydration directive\\. Please use a framework component for client rendering\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/integrations/mdx/src/satteri/hast-astro-metadata.ts","lineNumber":117,"sourceCode":"\tconst hasServerDefer = !hasClient && hasDirective(node, 'server:defer');\n\tif (!hasClient && !hasServerDefer) return;\n\n\tconst matchedImport = findMatchingImport(tagName, imports);\n\tif (!matchedImport) {\n\t\tthrow new Error(\n\t\t\t`Expected a matching import for component \\`${tagName}\\`. Did you forget to import it?`,\n\t\t);\n\t}\n\n\tif (matchedImport.path.endsWith('.astro') && hasClient) {\n\t\tlet clientAttr = 'client:*';\n\t\tfor (const a of node.attributes) {\n\t\t\tif (a.type === 'mdxJsxAttribute' && a.name.startsWith('client:')) {\n\t\t\t\tclientAttr = a.name;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t\tconsole.warn(\n\t\t\t`You are attempting to render <${tagName} ${clientAttr} />, but ${tagName} is an Astro component. Astro components do not render in the client and should not have a hydration directive. Please use a framework component for client rendering.`,\n\t\t);\n\t}\n\n\tconst resolvedPath = resolvePath(matchedImport.path, filePath);\n\tconst exportName =\n\t\tmatchedImport.name === '*' ? tagName.split('.').slice(1).join('.') : matchedImport.name;\n\n\tconst metadata = (ctx.data.__astroMetadata ??= createDefaultAstroMetadata());\n\tif (hasClient && findAttrValue(node, 'client:only') !== null) {\n\t\tmetadata.clientOnlyComponents.push({\n\t\t\texportName: matchedImport.name,\n\t\t\tlocalName: '',\n\t\t\tspecifier: tagName,\n\t\t\tresolvedPath,\n\t\t});\n\t\tctx.setProperty(node, 'client:display-name', tagName);\n\t\tctx.setProperty(node, 'client:component-path', resolvedPath);","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/integrations/mdx/src/satteri/hast-astro-metadata.ts#L99-L135","documentation":"The hast-based counterpart of the MDX metadata analyzer (used when JSX content flows through the markdown/hast pipeline): after matching an element to its import, if the import path ends in .astro and the node carries a client directive (hasClient), it warns that Astro components do not render in the client. The exact attribute name is included when one is found; otherwise the generic client:* placeholder is shown.","triggerScenarios":"An .mdx file (or markdown processed through the hast pipeline) using an imported .astro component with a client:* attribute — e.g. <Nav client:visible /> where Nav resolves to a .astro file. Warned during compilation of the containing file.","commonSituations":"Same as the rehype variant: docs and content sites in MDX, hydration directives copy-pasted from framework components, components migrated from React/Vue to .astro with leftover client: attributes.","solutions":["Drop the client:* attribute from the .astro component element","Hydrate a framework component embedded inside (or beside) the Astro component instead","If the directive was accidental, simply delete it to silence the warning"],"exampleFix":"# before  src/content/docs/page.mdx\nimport Nav from '../../components/Nav.astro';\n<Nav client:visible />\n\n# after\nimport Nav from '../../components/Nav.astro';\nimport Search from '../../components/Search.svelte';\n<Nav>\n  <Search client:visible slot=\"search\" />\n</Nav>","handlingStrategy":"type-guard","validationCode":"# CI review aid: surface all client: directives in MDX sources;\n# each hit whose component import ends in .astro is a bug\ngrep -rn --include='*.mdx' 'client:' src/content","typeGuard":"const isAstroComponentFactory = (c: unknown): c is () => any =>\n  typeof c === 'function' &&\n  (c as { isAstroComponentFactory?: boolean }).isAstroComponentFactory === true;\n\n// branch before attaching hydration props in shared/dynamic components\nconst hydration = isAstroComponentFactory(Comp) ? {} : { 'client:visible': true };","tryCatchPattern":null,"preventionTips":["Attach client:* in MDX only to framework components (React/Svelte/Vue/Solid)","When migrating a component to .astro, delete leftover client: attributes at every call site","Run the client: grep as a content-CI check"],"tags":["mdx","hydration","client-directive","astro-components","hast"],"backgroundTag":"hydration-directive-on-server-component","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}