{"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":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","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/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/integrations/node/src/index.ts#L16-L52","documentation":"The @astrojs/node adapter must know whether it serves the app itself (standalone, its own HTTP server) or plugs into an existing one (middleware exporting a handler). createIntegration throws immediately at config load if the options object is missing or has no truthy mode.","triggerScenarios":"Adding node() with no arguments to astro.config integrations; passing { mode: undefined } or a typo'd key like { mode: 'standalone' } spelled differently ({ modes: ... }); constructing the options object conditionally so mode ends up undefined.","commonSituations":"Copy-pasted config snippets that omit mode; refactors that made options optional; switching from another adapter whose integration takes no required options.","solutions":["Pass the mode explicitly: node({ mode: 'standalone' }) for the typical self-hosted setup","Use node({ mode: 'middleware' }) only when you embed the handler in your own HTTP server","Check the options object for typos and make sure it is actually passed to node()"],"exampleFix":"// before\nintegrations: [node()]\n// after\nintegrations: [node({ mode: 'standalone' })]","handlingStrategy":"validation","validationCode":"const nodeOptions: UserOptions = {\n  ...(env === 'embedded' ? { mode: 'middleware' as const } : { mode: 'standalone' as const }),\n};\nif (!nodeOptions.mode) throw new Error('node adapter mode must be set');\nintegrations: [node(nodeOptions)]","typeGuard":"type NodeAdapterMode = 'standalone' | 'middleware';\nfunction isNodeAdapterMode(v: unknown): v is NodeAdapterMode {\n  return v === 'standalone' || v === 'middleware';\n}","tryCatchPattern":null,"preventionTips":["Always write node({ mode: ... }) explicitly in astro.config","Treat mode as a required deployment decision, not an optional tweak","Add a config validation step in CI that imports the config and fails fast"],"tags":["node","adapter","config","required-option"],"backgroundTag":"missing-required-option","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"}