{"record":{"id":"9a47bc2cf4d153ee","repo":"sveltejs/kit","slug":"to-use-an-async-handleerror-hook-to-handle-error","errorCode":null,"errorMessage":"To use an async `handleError` hook to handle errors that occur during rendering, you must enable `compilerOptions.experimental.async` in the SvelteKit plugin of your Vite config. The returned error has been replaced with a generic object","messagePattern":"To use an async `handleError` hook to handle errors that occur during rendering, you must enable `compilerOptions\\.experimental\\.async` in the SvelteKit plugin of your Vite config\\. The returned error has been replaced with a generic object","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/kit/src/runtime/server/errors.js","lineNumber":99,"sourceCode":"\tfunction merge(body) {\n\t\treturn { ...fallback, ...body };\n\t}\n\n\t// TODO 4.0 await this, rather than handling the non-Promise case\n\tlet result;\n\ttry {\n\t\tconst input = { ...caught, event };\n\t\tif (__SVELTEKIT_DEV__) add_deprecated_handle_error_properties(input, fallback);\n\n\t\tresult = with_request_store({ event, state }, () => hooks.handleError(input));\n\t} catch (hook_error) {\n\t\tlog_handle_error_hook_failure(error, hook_error);\n\t\treturn { status: fallback.status, message: 'Internal Error' };\n\t}\n\n\tif (result instanceof Promise) {\n\t\tif (!__SVELTEKIT_SUPPORTS_ASYNC__ && state.is_in_render) {\n\t\t\tconsole.warn(\n\t\t\t\t`To use an async \\`handleError\\` hook to handle errors that occur during rendering, you must enable \\`compilerOptions.experimental.async\\` in the SvelteKit plugin of your Vite config. The returned error has been replaced with a generic object`\n\t\t\t);\n\n\t\t\t// we're discarding the result, but we still need to prevent an unhandled\n\t\t\t// rejection if the user's async `handleError` hook rejects\n\t\t\tresult.catch((hook_error) => log_handle_error_hook_failure(error, hook_error));\n\n\t\t\treturn {\n\t\t\t\tstatus: fallback.status,\n\t\t\t\tmessage: 'Internal Error'\n\t\t\t};\n\t\t}\n\n\t\treturn result.then(merge, (hook_error) => {\n\t\t\tlog_handle_error_hook_failure(error, hook_error);\n\t\t\treturn { status: fallback.status, message: 'Internal Error' };\n\t\t});\n\t}","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/sveltejs/kit/blob/03f1687fe612ce3d2d9131139b5b188d9cf90c64/packages/kit/src/runtime/server/errors.js#L81-L117","documentation":"SvelteKit calls the user's `handleError` hook when rendering errors. If the hook is async (returns a Promise) but async Svelte support is not enabled, the result cannot be awaited and is discarded/replaced with a generic object, with this warning. It prevents unhandled rejections from the user's async hook.","triggerScenarios":"An async `handleError` hook in hooks.server.js runs during rendering while `__SVELTEKIT_SUPPORTS_ASYNC__` is false and the error originated in render state; `compilerOptions.experimental.async` is not enabled in the SvelteKit Vite plugin options.","commonSituations":"Upgrading to async Svelte components without opting in via the compiler flag; logging errors to an external service with `await fetch` inside handleError; mixing Svelte 4-style sync assumptions with Svelte 5 async rendering.","solutions":["Enable the experimental async compiler option in vite.config: `sveltekit({ compilerOptions: { experimental: { async: true } } })`","Make `handleError` synchronous, or fire-and-forget async work with explicit `.catch` handling","Upgrade Svelte/SvelteKit so async support is stable and enabled by default"],"exampleFix":"// vite.config.js before\nsveltekit()\n// after\nsveltekit({ compilerOptions: { experimental: { async: true } } })","handlingStrategy":"try-catch","validationCode":"// in hooks.server.js, prefer sync hook unless async is enabled\nconst isAsyncHook = handleError.constructor.name === 'AsyncFunction';\nif (isAsyncHook) console.warn('Enable compilerOptions.experimental.async or make handleError sync');","typeGuard":null,"tryCatchPattern":"// keep async work from becoming unhandled rejections\ntry {\n  const r = handleError(error, event);\n  if (r instanceof Promise) r.catch((e) => console.error('hook failed', e));\n} catch (e) {\n  console.error('hook failed', e);\n}","preventionTips":["Enable experimental.async when using async handleError","Or keep handleError synchronous and use fire-and-forget with .catch","Check Svelte/SvelteKit version notes when migrating"],"tags":["hooks","async","handleerror","compiler-options"],"backgroundTag":"async-hook-not-supported","analyzedSha":"03f1687fe612ce3d2d9131139b5b188d9cf90c64","analyzedAt":"2026-09-02T02:01:50.504Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}