{"record":{"id":"fbd8082ed2ef932a","repo":"withastro/astro","slug":"setting-the-mode-option-is-required","errorCode":null,"errorMessage":"Setting the 'mode' option is required.","messagePattern":"Setting the 'mode' option is required\\.","errorType":"validation","errorClass":"AstroError","httpStatus":null,"severity":"critical","filePath":"packages/integrations/node/src/index.ts","lineNumber":34,"sourceCode":"\t\tadapterFeatures: {\n\t\t\tbuildOutput: 'server',\n\t\t\tmiddlewareMode: 'classic',\n\t\t\tstaticHeaders,\n\t\t},\n\t\tsupportedAstroFeatures: {\n\t\t\thybridOutput: 'stable',\n\t\t\tstaticOutput: 'stable',\n\t\t\tserverOutput: 'stable',\n\t\t\tsharpImageService: 'stable',\n\t\t\ti18nDomains: 'experimental',\n\t\t\tenvGetSecret: 'stable',\n\t\t},\n\t};\n}\n\nexport default function createIntegration(userOptions: UserOptions): AstroIntegration {\n\tif (!userOptions?.mode) {\n\t\tthrow new AstroError(`Setting the 'mode' option is required.`);\n\t}\n\n\tlet _config: AstroConfig | undefined = undefined;\n\tlet _routeToHeaders: RouteToHeaders | undefined = undefined;\n\treturn {\n\t\tname: '@astrojs/node',\n\t\thooks: {\n\t\t\t'astro:config:setup': async ({ updateConfig, config, logger, command }) => {\n\t\t\t\tlet session = config.session;\n\t\t\t\t_config = config;\n\t\t\t\tif (session !== false && !session?.driver) {\n\t\t\t\t\tlogger.info('Enabling sessions with filesystem storage');\n\t\t\t\t\tsession = {\n\t\t\t\t\t\tdriver: sessionDrivers.fsLite({\n\t\t\t\t\t\t\tbase: fileURLToPath(new URL('sessions', config.cacheDir)),\n\t\t\t\t\t\t}),\n\t\t\t\t\t\tcookie: session?.cookie,\n\t\t\t\t\t\tttl: session?.ttl,","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/node/src/index.ts#L16-L52","documentation":"Thrown by the @astrojs/node adapter when its integration factory is called without a `mode` option. The adapter cannot decide whether to run as a standalone server or as Express/connect middleware, so it aborts at config setup. `mode` is a required field on UserOptions, not optional at runtime.","triggerScenarios":"Calling `node({ /* missing mode */ })` as the `adapter` in `astro.config`. Passing `mode: undefined` or `mode: ''` (falsy) also triggers it because the guard is `if (!userOptions?.mode)`.","commonSituations":"Upgrading to a Node adapter major version that promoted `mode` from optional-with-default to required. Copying an old config snippet that only set `mode: 'standalone'` conditionally. Spreading a partial options object that omits the key.","solutions":["Set `mode: 'standalone'` in the adapter options for a normal Node HTTP server (default use case).","Set `mode: 'middleware'` if you are mounting Astro inside an existing Express/Connect/Polka server via the exported `handler`.","Confirm the option is on the adapter call itself: `adapter: node({ mode: 'standalone' })`, not elsewhere in the config."],"exampleFix":"// before\nimport node from '@astrojs/node';\nexport default defineConfig({ adapter: node() });\n// after\nimport node from '@astrojs/node';\nexport default defineConfig({ adapter: node({ mode: 'standalone' }) });","handlingStrategy":"type-guard","validationCode":"import type { UserOptions } from '@astrojs/node';\nfunction assertNodeOptions(o: Partial<UserOptions>): asserts o is UserOptions {\n  if (!o.mode || (o.mode !== 'standalone' && o.mode !== 'middleware')) {\n    throw new Error('node adapter requires mode: \\'standalone\\' | \\'middleware\\'');\n  }\n}\nassertNodeOptions(opts);","typeGuard":"function isValidNodeMode(m: unknown): m is 'standalone' | 'middleware' {\n  return m === 'standalone' || m === 'middleware';\n}","tryCatchPattern":null,"preventionTips":["Treat the adapter options object as strongly typed via `satisfies UserOptions`.","Centralize adapter construction in one config module so mode is never omitted by a partial spread.","Add a unit test asserting the config calls node() with a valid mode."],"tags":["node-adapter","config","astro","build-config"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}