{"record":{"id":"826f74c4828f25b7","repo":"withastro/astro","slug":"error-invalid-hydration-directive-key-suppo","errorCode":null,"errorMessage":"Error: invalid hydration directive \"${key}\". Supported hydration methods: ${hydrationMethods}","messagePattern":"Error: invalid hydration directive \"(.+?)\"\\. Supported hydration methods: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/runtime/server/hydration.ts","lineNumber":86,"sourceCode":"\t\t\t\t}\n\t\t\t\t// This is a special prop added to prove that the client hydration method\n\t\t\t\t// was added statically.\n\t\t\t\tcase 'client:component-hydration': {\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase 'client:display-name': {\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tdefault: {\n\t\t\t\t\textracted.hydration.directive = key.split(':')[1];\n\t\t\t\t\textracted.hydration.value = value;\n\n\t\t\t\t\t// throw an error if an invalid hydration directive was provided\n\t\t\t\t\tif (!clientDirectives.has(extracted.hydration.directive)) {\n\t\t\t\t\t\tconst hydrationMethods = Array.from(clientDirectives.keys())\n\t\t\t\t\t\t\t.map((d) => `client:${d}`)\n\t\t\t\t\t\t\t.join(', ');\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t`Error: invalid hydration directive \"${key}\". Supported hydration methods: ${hydrationMethods}`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\n\t\t\t\t\t// throw an error if the query wasn't provided for client:media\n\t\t\t\t\tif (\n\t\t\t\t\t\textracted.hydration.directive === 'media' &&\n\t\t\t\t\t\ttypeof extracted.hydration.value !== 'string'\n\t\t\t\t\t) {\n\t\t\t\t\t\tthrow new AstroError(AstroErrorData.MissingMediaQueryDirective);\n\t\t\t\t\t}\n\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t} else {\n\t\t\textracted.props[key] = value;\n\t\t\tif (!transitionDirectivesToCopyOnIsland.includes(key)) {","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/runtime/server/hydration.ts#L68-L104","documentation":"While extracting directives before SSR of a framework component, Astro validates every client:* attribute against the registered client directives (client:load, client:idle, client:visible, client:media, client:only; client:display-name is special-cased and skipped). An unknown directive name is a hard error listing the supported methods, thrown at render time.","triggerScenarios":"A typo like client:onload, client:visable, or client:scroll on a framework component; a directive name that is not registered because the integration providing it (via its clientDirectives hook) is not installed or not enabled in astro.config; code written for a custom directive whose integration was removed.","commonSituations":"Typos in directives; copy-pasting examples that rely on a custom client directive from an integration that is not in the project; upgrading and dropping an integration that registered extra directives.","solutions":["Correct the directive to one of client:load, client:idle, client:visible, client:media, client:only","If a custom hydration strategy is intended, register it via an integration's clientDirectives hook in astro.config.mjs","Search the codebase for 'client:' typos (rg 'client:[a-z]+' ) to catch sibling mistakes"],"exampleFix":"// before\n<Counter client:onload />\n\n// after\n<Counter client:load />","handlingStrategy":"validation","validationCode":"const SUPPORTED = new Set(['load', 'idle', 'visible', 'media', 'only']);\nfunction assertClientDirective(key: string) {\n  const name = key.split(':')[1];\n  if (!SUPPORTED.has(name)) {\n    throw new Error('Unknown hydration directive: client:' + name);\n  }\n}","typeGuard":"function isSupportedDirective(key: string): boolean {\n  return ['load', 'idle', 'visible', 'media', 'only'].includes(key.split(':')[1] ?? '');\n}","tryCatchPattern":null,"preventionTips":["Memorize the five built-ins: client:load, client:idle, client:visible, client:media, client:only","Grep for 'client:' to catch typos before build","Register custom directives via an integration's clientDirectives hook rather than inventing attribute names"],"tags":["astro","hydration","directive","typo"],"backgroundTag":"unknown-hydration-directive","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"}