withastro/astro · error · Error

[astro:actions] `getActionContext()` unexpectedly used on…

Error message

[astro:actions] `getActionContext()` unexpectedly used on the client.

What it means

getActionContext() reads per-request state (locals, params, cookies, the action's name and calledFrom mode) and therefore only exists during server request handling. The client build of astro:actions replaces it with a throwing stub, so any browser-side execution fails with this message instead of silently returning an unusable context.

Solutions

Keep getActionContext() calls in server-only files: actions handlers, .astro frontmatter, API endpoints, middleware
Pass whatever data the client needs (action name, result) down as props instead of reading context in the browser
If a shared module must branch, guard with if (import.meta.env.SSR) before calling it

Example fix

// before — src/components/Status.jsx (client:load)
import { getActionContext } from 'astro:actions';
const ctx = getActionContext(Astro); // browser -> throws

// after — pass data from the server page
// Astro page (server):
const ctx = getActionContext(Astro);
---
// src/components/Status.jsx (client)
export default function Status({ actionName }) { return <p>{actionName}</p>; }

Defensive patterns

Strategy: validation

Validate before calling

// branch on environment before touching server-only APIs
if (import.meta.env.SSR) {
  const ctx = getActionContext(Astro);
  // use ctx safely
} else {
  // derive equivalent data from props/state in the browser
}

Prevention

Treat getActionContext as server-only API: only call it in handlers, pages, endpoints, middleware
Pass request-derived data to client components as props rather than reading context there
Name server-only files clearly (e.g. *.server.ts) so they are never imported into browser bundles

When it happens

Trigger: Calling getActionContext() inside a <script>, a client-side framework component, or any module that only runs in the browser. Importing server runtime code (e.g. from astro:actions/server.js or a file that calls getActionContext) into a client bundle.

Common situations: Copying middleware-style context code into a client component; sharing a utility that reads action context between server and client files; importing an Astro page module's helper into client code.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/14f3ec11b7f78149. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/actions/runtime/entrypoints/client.ts:32

	ActionError,
	isActionError,
	isInputError,
} from '../client.js';
export type {
	ActionAPIContext,
	ActionClient,
	ActionErrorCode,
	ActionInputSchema,
	ActionReturnType,
	SafeResult,
} from '../types.js';

export function defineAction() {
	throw new Error('[astro:actions] `defineAction()` unexpectedly used on the client.');
}

export function getActionContext() {
	throw new Error('[astro:actions] `getActionContext()` unexpectedly used on the client.');
}

export const getActionPath = createGetActionPath({
	baseUrl: import.meta.env.BASE_URL,
	shouldAppendTrailingSlash,
});

export const actions = createActionsProxy({
	handleAction: async (param, path) => {
		const headers = new Headers();
		headers.set('Accept', 'application/json');
		// Apply adapter-specific headers for internal fetches
		for (const [key, value] of Object.entries(internalFetchHeaders)) {
			headers.set(key, value);
		}
		let body = param;
		if (!(body instanceof FormData)) {
			try {

View on GitHub (pinned to 52e6c34790)