sveltejs/svelte · error · Error

experimental_async_required

experimental_async_required

Error message

experimental_async_required
Cannot use `${name}(...)` unless the `experimental.async` compiler option is `true`
https://svelte.dev/e/experimental_async_required

What it means

Svelte's experimental async component support (e.g. top-level `await` in a component `<script>`) must be opted into via the `experimental.async` compiler option. Without it, the compiler emits a call to `experimental_async_required(name)`, which throws at runtime when the async feature is invoked. The message names the specific feature (`%name%`) that triggered it.

Source

Thrown at packages/svelte/src/internal/shared/errors.js:18

/* This file is generated by scripts/process-messages/index.js. Do not edit! */

import { DEV } from 'esm-env';

/**
 * Cannot use `%name%(...)` unless the `experimental.async` compiler option is `true`
 * @param {string} name
 * @returns {never}
 */
export function experimental_async_required(name) {
	if (DEV) {
		const error = new Error(`experimental_async_required\nCannot use \`${name}(...)\` unless the \`experimental.async\` compiler option is \`true\`\nhttps://svelte.dev/e/experimental_async_required`);

		error.name = 'Svelte error';

		throw error;
	} else {
		throw new Error(`https://svelte.dev/e/experimental_async_required`);
	}
}

/**
 * Cannot use `{@render children(...)}` if the parent component uses `let:` directives. Consider using a named snippet instead
 * @returns {never}
 */
export function invalid_default_snippet() {
	if (DEV) {
		const error = new Error(`invalid_default_snippet\nCannot use \`{@render children(...)}\` if the parent component uses \`let:\` directives. Consider using a named snippet instead\nhttps://svelte.dev/e/invalid_default_snippet`);

		error.name = 'Svelte error';

		throw error;
	} else {
		throw new Error(`https://svelte.dev/e/invalid_default_snippet`);
	}
}

View on GitHub (pinned to 20b341f100)

Solutions

1. Enable the option: in `svelte.config.js` set `export default { compilerOptions: { experimental: { async: true } } }`.
2. Remove the async feature and refactor top-level `await` into `onMount`/`$effect` with explicit loading state.
3. Verify the compiler picks up the config (Vite/SvelteKit plugin options) — rebuild after changing config.

Example fix

// before — svelte.config.js
export default { compilerOptions: {} };
// after
export default { compilerOptions: { experimental: { async: true } } };

// assert experimental.async is enabled before building
import { readFileSync } from 'fs';
const cfg = readFileSync('svelte.config.js', 'utf8');
if (!/experimental\s*:\s*\{\s*async\s*:\s*true/.test(cfg)) {
	throw new Error('experimental.async must be true for async components');
}

When it happens

Trigger: Using an async-only Svelte feature — such as top-level `await` in a `.svelte` `<script>` — without `compilerOptions.experimental.async = true` in `svelte.config.js` or the Vite plugin config. The compiled output calls the guard function, which throws.

Common situations: Following docs/tutorials that assume experimental async is enabled; upgrading Svelte where the flag reset to its default `false`; using a library that depends on async components.

Related errors

• 'svelte/compiler' no longer exports a `walk` utility — pleas
• async_derived_orphan
• fork_discarded
• fork_timing
• hydratable_missing_but_required

AI-assisted analysis of sveltejs/svelte@20b341f100 (2026-08-12). Data as JSON: /api/errors/70f6b2d35f8aec20. Report an issue: GitHub.