withastro/astro · error · Error

Error: invalid hydration directive "${key}". Supported hydra

Error message

Error: invalid hydration directive "${key}". Supported hydration methods: ${hydrationMethods}

What it means

During prop extraction for a component, Astro encountered a `client:` attribute whose directive (the part after the colon) is not in the registered `clientDirectives` set. The built-in supported set is `load`, `idle`, `visible`, `media`, `only` (plus the internal `display-name`). Any other value is rejected at render time.

Source

Thrown at packages/astro/src/runtime/server/hydration.ts:86

				}
				// This is a special prop added to prove that the client hydration method
				// was added statically.
				case 'client:component-hydration': {
					break;
				}
				case 'client:display-name': {
					break;
				}
				default: {
					extracted.hydration.directive = key.split(':')[1];
					extracted.hydration.value = value;

					// throw an error if an invalid hydration directive was provided
					if (!clientDirectives.has(extracted.hydration.directive)) {
						const hydrationMethods = Array.from(clientDirectives.keys())
							.map((d) => `client:${d}`)
							.join(', ');
						throw new Error(
							`Error: invalid hydration directive "${key}". Supported hydration methods: ${hydrationMethods}`,
						);
					}

					// throw an error if the query wasn't provided for client:media
					if (
						extracted.hydration.directive === 'media' &&
						typeof extracted.hydration.value !== 'string'
					) {
						throw new AstroError(AstroErrorData.MissingMediaQueryDirective);
					}

					break;
				}
			}
		} else {
			extracted.props[key] = value;
			if (!transitionDirectivesToCopyOnIsland.includes(key)) {

View on GitHub (pinned to d081033d5f)

Solutions

1. Correct the directive to one of the supported methods listed in the error message (`client:load`, `client:idle`, `client:visible`, `client:media`, `client:only`).
2. Check for the exact spelling and casing (directives are lowercase).
3. If you need a custom directive, register it via the `clientDirectives` integration hook before using it.

Example fix

// before
<Counter client:visble />

// after
<Counter client:visible />

const SUPPORTED = new Set(['load', 'idle', 'visible', 'media', 'only']);
function assertDirective(attr: string): void {
  const name = attr.slice('client:'.length);
  if (!SUPPORTED.has(name)) {
    throw new Error(`Unsupported client directive: client:${name}`);
  }
}

const isClientDirective = (attr: string): boolean =>
  SUPPORTED.has(attr.split(':')[1]);

When it happens

Trigger: A typo in the directive (`client:visble`, `client:idel`); an experimental/custom directive that was never registered; using a directive from a newer/older Astro version that the current install doesn't ship.

Common situations: Spelling mistakes on hydration directives; assuming a directive like `client:scroll` or `client:intersection` exists; copying example code from docs for a different Astro version.

Related errors

• MissingMediaQueryDirective
• NoMatchingImport
• NoClientOnlyHint
• You tried to add the ${name} client renderer, but its server
• Invalid component export path: ${componentExport}

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/826f74c4828f25b7. Report an issue: GitHub.