{"record":{"id":"50e7511f6be974f6","repo":"withastro/astro","slug":"astro-actions-defineaction-unexpectedly-used","errorCode":null,"errorMessage":"[astro:actions] `defineAction()` unexpectedly used on the client.","messagePattern":"\\[astro:actions\\] `defineAction\\(\\)` unexpectedly used on the client\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/actions/runtime/entrypoints/client.ts","lineNumber":28,"sourceCode":"} from '../client.js';\n\nexport { ACTION_QUERY_PARAMS } from '../../consts.js';\nexport {\n\tActionError,\n\tisActionError,\n\tisInputError,\n} from '../client.js';\nexport type {\n\tActionAPIContext,\n\tActionClient,\n\tActionErrorCode,\n\tActionInputSchema,\n\tActionReturnType,\n\tSafeResult,\n} from '../types.js';\n\nexport function defineAction() {\n\tthrow new Error('[astro:actions] `defineAction()` unexpectedly used on the client.');\n}\n\nexport function getActionContext() {\n\tthrow new Error('[astro:actions] `getActionContext()` unexpectedly used on the client.');\n}\n\nexport const getActionPath = createGetActionPath({\n\tbaseUrl: import.meta.env.BASE_URL,\n\tshouldAppendTrailingSlash,\n});\n\nexport const actions = createActionsProxy({\n\thandleAction: async (param, path) => {\n\t\tconst headers = new Headers();\n\t\theaders.set('Accept', 'application/json');\n\t\t// Apply adapter-specific headers for internal fetches\n\t\tfor (const [key, value] of Object.entries(internalFetchHeaders)) {\n\t\t\theaders.set(key, value);","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/actions/runtime/entrypoints/client.ts#L10-L46","documentation":"Astro ships two builds of the astro:actions runtime: a server build where defineAction() registers handlers, and a client build where defineAction() is a stub that throws. If code that defines actions gets bundled for the browser (where no server handler can exist), executing it hits the stub and fails immediately with this message.","triggerScenarios":"Calling defineAction() inside a <script> tag, a client-imported framework component, or any file that is reached from the browser bundle — most commonly by relatively importing src/actions/index.ts from client code instead of using the astro:actions virtual module.","commonSituations":"Reusing schema/handler code by importing the actions file into a client component; accidentally adding 'use client'/client:load directives up the import chain of the actions file; bundling shared utilities that transitively import the actions index.","solutions":["In browser code, import only the callable proxy from 'astro:actions' — never relatively import src/actions/index.ts","Move shared zod schemas and helpers into a separate schema.ts module that both the actions file and client components import","Check the import chain of the failing file for client directives (<script>, client:*, use client) and cut the actions file out of it"],"exampleFix":"// before — ClientComponent.jsx\nimport { server } from '../../actions/index.js'; // pulls defineAction into browser bundle\n\n// after\nimport { actions } from 'astro:actions'; // client-safe proxy\nimport { blogSchema } from '../../actions/schema'; // shared zod schema, no defineAction","handlingStrategy":"validation","validationCode":"// guard any accidental client-side execution\nif (typeof defineAction === 'function' && !import.meta.env.SSR) {\n  throw new Error('This module defines actions and must not ship to the browser');\n}","typeGuard":"// keep definitions physically separated so no guard is needed at runtime:\n// actions/*.ts (server-only, calls defineAction) vs actions/schema.ts (isomorphic)","tryCatchPattern":null,"preventionTips":["Client code imports only { actions } from 'astro:actions'; never relatively import src/actions/index.ts","Keep zod schemas in a separate isomorphic module both sides can import","Review client directives (<script>, client:*, 'use client') on any component chain that touches action definitions"],"tags":["astro-actions","ssr","client-bundle","isomorphic-import"],"backgroundTag":"server-code-in-client-bundle","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"}