withastro/astro · critical · Error

The `typescript.tsdk` init option is required. It should poi

Error message

The `typescript.tsdk` init option is required. It should point to a directory containing a `typescript.js` or `tsserverlibrary.js` file, such as `node_modules/typescript/lib`.

What it means

Thrown by the Astro language server's Node server (`nodeServer.ts`) on LSP `initialize` when the client did not pass `initializationOptions.typescript.tsdk`. The server needs a TypeScript lib directory to load `typescript.js`/`tsserverlibrary.js` for language features; without it the server cannot start.

Source

Thrown at packages/language-tools/language-server/src/nodeServer.ts:31

	type CollectionConfigInstance,
	SUPPORTED_FRONTMATTER_EXTENSIONS_KEYS,
} from './core/frontmatterHolders.js';
import { addAstroTypes } from './core/index.js';
import { getLanguagePlugins, getLanguageServicePlugins } from './languageServerPlugin.js';
import { getAstroInstall } from './utils.js';

const connection = createConnection();
const server = createServer(connection);

let contentIntellisenseEnabled = false;

connection.listen();

connection.onInitialize((params) => {
	const tsdk = params.initializationOptions?.typescript?.tsdk;

	if (!tsdk) {
		throw new Error(
			'The `typescript.tsdk` init option is required. It should point to a directory containing a `typescript.js` or `tsserverlibrary.js` file, such as `node_modules/typescript/lib`.',
		);
	}

	const { typescript, diagnosticMessages } = loadTsdkByPath(tsdk, params.locale);

	contentIntellisenseEnabled = params.initializationOptions?.contentIntellisense ?? false;
	const collectionConfig = {
		reload(folders) {
			this.configs = loadCollectionConfig(folders);
		},
		configs: contentIntellisenseEnabled
			? loadCollectionConfig(
					// The vast majority of clients support workspaceFolders, but sometimes some unusual environments like tests don't
					// @ts-expect-error - Just deprecated types, it's fine
					params.workspaceFolders ?? (params.rootUri ? [{ uri: params.rootUri }] : []) ?? [],
				)
			: [],

View on GitHub (pinned to d081033d5f)

Solutions

1. Configure the LSP client to send `initializationOptions: { typescript: { tsdk: '<workspace>/node_modules/typescript/lib' } }`.
2. Use the official Astro editor extension, which sets this automatically.
3. Ensure `typescript` is installed in the workspace so the lib path resolves.

Example fix

// before: language client init without options
const client = new LanguageClient({ id: 'astro', serverOptions });
// after
const client = new LanguageClient({
  id: 'astro',
  serverOptions,
  clientOptions: {
    initializationOptions: {
      typescript: { tsdk: require('path').dirname(require.resolve('typescript')) },
    },
  },
});

function assertTsdk(init: any) {
  if (!init?.typescript?.tsdk) {
    throw new Error('Client must send initializationOptions.typescript.tsdk');;
  }
}

function hasTsdk(init: unknown): init is { typescript: { tsdk: string } } {
  return typeof (init as any)?.typescript?.tsdk === 'string';
}

When it happens

Trigger: An editor/LSP client starting `@astrojs/language-server`/`astro-languageserver` without sending `initializationOptions.typescript.tsdk` in the `initialize` request. A misconfigured editor extension. A custom LSP wrapper that omits init options.

Common situations: Using a non-standard editor integration that doesn't set the tsdk. The VS Code Astro extension failing to forward the tsdk. Programmatic embedding of the language server without init options.

Related errors

• The TypeScript module loaded${version} does not expose the p
• Specified tsconfig file `${tsconfig}` does not exist.
• GetStaticPathsInvalidRouteParam
• GenerateContentTypesError
• Integration ${integrationName} is injecting a type that does

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/f02938a52b6b6aa2. Report an issue: GitHub.