withastro/astro · error · AstroError

InvalidComponentArgs

InvalidComponentArgs

Error message

Invalid arguments passed to <${name}> component.

What it means

Every Astro component factory is wrapped by `baseCreateComponent`, which validates invocation through `validateArgs`: it requires exactly 3 arguments and that the first argument is a non-null object (the props). If a component is called with the wrong shape (e.g. by bypassing the compiler's call convention or manually invoking the factory), Astro throws `InvalidComponentArgs`.

Source

Thrown at packages/astro/src/runtime/server/astro-component.ts:18

import { AstroError, AstroErrorData } from '../../core/errors/index.js';
import type { PropagationHint } from '../../types/public/internal.js';
import type { AstroComponentFactory } from './render/index.js';

function validateArgs(args: unknown[]): args is Parameters<AstroComponentFactory> {
	if (args.length !== 3) return false;
	if (!args[0] || typeof args[0] !== 'object') return false;
	return true;
}
function baseCreateComponent(
	cb: AstroComponentFactory,
	moduleId?: string,
	propagation?: PropagationHint,
): AstroComponentFactory {
	const name = moduleId?.split('/').pop()?.replace('.astro', '') ?? '';
	const fn = (...args: Parameters<AstroComponentFactory>) => {
		if (!validateArgs(args)) {
			throw new AstroError({
				...AstroErrorData.InvalidComponentArgs,
				message: AstroErrorData.InvalidComponentArgs.message(name),
			});
		}
		return cb(...args);
	};
	Object.defineProperty(fn, 'name', { value: name, writable: false });
	// Add a flag to this callback to mark it as an Astro component
	fn.isAstroComponentFactory = true;
	fn.moduleId = moduleId;
	fn.propagation = propagation;
	return fn;
}

interface CreateComponentOptions {
	factory: AstroComponentFactory;
	moduleId?: string;
	propagation?: PropagationHint;

View on GitHub (pinned to d081033d5f)

Solutions

1. Render `.astro` components through Astro's normal rendering pipeline (the compiler-generated call), not by manual function invocation.
2. If invoking programmatically, pass the expected 3-tuple: `(props, metadata, AstroGlobals)`-style arguments matching `AstroComponentFactory`.
3. Regenerate compiled output (`astro build`/`astro sync`) in case of stale artifacts.

Example fix

// before — manual call with wrong arity
const html = MyComponent({ name: 'x' })

// after — render via Astro's API (e.g. render() from 'astro:render')
import { render } from 'astro:render'
const html = await render(MyComponent, { name: 'x' })

function isValidComponentCall(args) {
  return Array.isArray(args) && args.length === 3 &&
    args[0] != null && typeof args[0] === 'object';
}

function isAstroComponentCall(args) {
  return Array.isArray(args) && args.length === 3 &&
    typeof args[0] === 'object' && args[0] !== null;
}

null

When it happens

Trigger: Manually invoking a compiled `.astro` component factory with the wrong number of arguments, or with a non-object first argument — typically from hand-written code rather than the Astro compiler's generated calls.

Common situations: Calling a `.astro` component as a plain function `MyComponent({ x: 1 })` instead of via the renderer; a corrupted/older compiled output that calls the factory incorrectly; a custom integration invoking component factories directly with the wrong signature.

Related errors

• RenderUndefinedEntryError
• Invalid component export path: ${componentExport}
• UnknownContentCollectionError
• Failed to parse image reference: ${imagePath}
• CacheNotEnabled

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