fix: handle unhandled exceptions in LSP server and VS Code extension (#10567)

## Problem

Multiple unhandled exceptions can escape to the VS Code extension host,
causing error telemetry and degraded user experience:

1. **Server crash with no user notification** — When the LSP server
process terminates unexpectedly, the default `LanguageClient` behavior
silently retries and eventually gives up without informing the user.

2. **DocumentSymbol crash** (`"name must not be falsy"`) — When the
TypeSpec compiler returns a document symbol with an empty name (e.g.,
from empty string literal properties or parse error recovery), VS Code's
`DocumentSymbol` constructor rejects it. This throws in the
`vscode-languageclient` protocol converter, which has no extension-level
catch.

3. **Server handler crashes** (`"Cannot read properties of undefined
(reading 'kind')"`) — `getSymNode()` can return `undefined` when a
symbol's `declarations` array is empty, but callers access `.kind`
without null checks. This crashes hover, completion, and signature help
requests.

4. **Extension command exceptions escape** — Commands like
`ShowOpenApi3`, `EmitCode`, and `RestartServer` can throw unhandled
exceptions that propagate through `doOperationWithTelemetry` (which
re-throws after logging telemetry).

## Fix

### VS Code Extension (`packages/typespec-vscode`)

- **Custom `ErrorHandler`** on the `LanguageClient`: Shows a
notification with "Restart Server" button when the server crashes,
instead of silently failing.
- **`onUnhandledException` callback** added to all
`doOperationWithTelemetry` calls: Allows callers to handle exceptions
gracefully (log + show notification) instead of re-throwing to the
extension host. The callback now returns `T` so each caller provides the
correct typed fallback value.
- **All commands covered**: `StartExtension`, `EmitCode`,
`RestartServer`, `InstallGlobalCompilerCli`, `CreateProject`,
`ImportFromOpenApi3`, `ShowOpenApi3`, `ServerPathSettingChanged`,
`StartServer` — every command now has proper exception handling.
- **`recreateLSPClient` wrapped in try-catch**: Catches any unexpected
errors during server startup/restart and shows a user notification.
- **Null guard for `tspLanguageClient`** in `ShowOpenApi3` command:
Prevents `TypeError` when client is undefined.
- **`resolveTypeSpecServer` no longer throws**: Invalid `TspServerPath`
config now logs an error and returns `undefined` instead of throwing.
- **`deactivate()` wrapped in try-catch**: Prevents errors during
extension shutdown from crashing the host.

### Compiler LSP Server (`packages/compiler`)

- **DocumentSymbol empty name fix**: `createDocumentSymbol()` now uses
`"<anonymous>"` fallback when name is empty/falsy.
- **5 `getSymNode()` null check fixes**:
  - `serverlib.ts` (hover): `sn.kind` → `sn && sn.kind`
  - `type-details.ts`: Guard before `getTypeOrValueForNode()`
  - `type-signature.ts`: Guard before `getTypeOrValueForNode()`
- `completion.ts`: Guard before `getTypeForNode()` and `symNode?.kind`
for namespace check

### Telemetry Improvements

- **Added `compilerStartType` property** to
`OperationDetailPropertyName` enum to track how the server was launched
(`node` vs `standalone-tsp-cli`).
- **Compiler resolution telemetry**: Every branch in
`resolveTypeSpecServer` now logs to telemetry — invalid setting type,
local/global/configured resolution, development mode, and the "skipped"
case when no workspace is open.
- **Missing error telemetry filled**: Added
`logOperationDetailTelemetry` calls for error paths in `emit-code.ts`
(LSP client null, empty compile result) and `openapi3-preview.ts` (temp
folder creation failure).
- **`tel.lastStep` annotations**: Added to LSP client null-guard
branches in `EmitCode` and `ShowOpenApi3` for easier troubleshooting.
- **`recreateLSPClient` improved**: Error messages now include client
state and specific failure reason for better diagnostics.

## Testing

- All 17 document symbol tests pass
- All 732 server tests pass (3 pre-existing failures in rename-files
unrelated to this change)
- TypeScript compilation clean (`tsc --noEmit`)
- VS Code extension unit tests pass

---------

Co-authored-by: Copilot <copilot@github.com>

Author: RodgeFu

.chronus/changes/fix-compiler-server-null-crashes-2026-4-30-7-30-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/compiler"
+---
+
+Fix server crashes caused by undefined symbol declarations: add null checks for `getSymNode()` in hover, completion, type-details, and type-signature handlers, and use fallback name for empty DocumentSymbol names

.chronus/changes/fix-lsp-unhandled-exceptions-2026-4-30-7-30-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - typespec-vscode
+---
+
+Handle unhandled exceptions in VS Code extension: add custom error handler for server crashes with restart notification, wrap commands with graceful exception handling, and add null guards to prevent extension host errors when LSP client is unavailable

packages/compiler/src/server/completion.ts

@@ -421,20 +421,20 @@ async function addIdentifierCompletion(
     let kind: CompletionItemKind;
     let deprecated = false;
     const symNode = getSymNode(sym);
-    const type = sym.type ?? program.checker.getTypeForNode(symNode);
+    const type = sym.type ?? (symNode ? program.checker.getTypeForNode(symNode) : undefined);
     if (sym.flags & (SymbolFlags.Function | SymbolFlags.Decorator)) {
       kind = CompletionItemKind.Function;
     } else if (
       sym.flags & SymbolFlags.Namespace &&
-      symNode.kind !== SyntaxKind.NamespaceStatement
+      symNode?.kind !== SyntaxKind.NamespaceStatement
     ) {
       kind = CompletionItemKind.Module;
     } else if (symNode?.kind === SyntaxKind.AliasStatement) {
       kind = CompletionItemKind.Variable;
       deprecated = getDeprecationDetails(program, symNode) !== undefined;
     } else {
-      kind = getCompletionItemKind(program, type);
-      deprecated = getDeprecationDetails(program, type) !== undefined;
+      kind = type ? getCompletionItemKind(program, type) : CompletionItemKind.Variable;
+      deprecated = type ? getDeprecationDetails(program, type) !== undefined : false;
     }
     const documentation = await getSymbolDetails(program, sym);
 

packages/compiler/src/server/serverlib.ts

@@ -822,7 +822,7 @@ export function createServer(
       // Avoid showing full definition in other cases which can be long and not useful
       let includeExpandedDefinition = false;
       const sn = getSymNode(sym[0]);
-      if (sn.kind !== SyntaxKind.AliasStatement) {
+      if (sn && sn.kind !== SyntaxKind.AliasStatement) {
         const type = sym[0].type ?? program.checker.getTypeOrValueForNode(sn);
         if (type && "kind" in type) {
           const modelHasExtendOrIs: boolean =

packages/compiler/src/server/symbol-structure.ts

@@ -109,7 +109,10 @@ export function getSymbolStructure(ast: TypeSpecScriptNode): DocumentSymbol[] {
     const start = file.getLineAndCharacterOfPosition(node.pos);
     const end = file.getLineAndCharacterOfPosition(node.end);
     const range = Range.create(start, end);
-    return DocumentSymbol.create(name, undefined, kind, range, range, symbols);
+    // VS Code requires name to be non-empty; use a placeholder for empty/invalid names
+    // that can occur during parse errors or with empty string literal properties.
+    const safeName = name || "<anonymous>";
+    return DocumentSymbol.create(safeName, undefined, kind, range, range, symbols);
   }
 
   function getName(id: IdentifierNode | StringLiteralNode): string {

packages/compiler/src/server/type-details.ts

@@ -80,9 +80,12 @@ function getSymbolDocumentation(program: Program, symbol: Sym) {
   // Add @doc(...) API docs
   let type = symbol.type;
   if (!type) {
-    const entity = program.checker.getTypeOrValueForNode(getSymNode(symbol));
-    if (entity && isType(entity)) {
-      type = entity;
+    const symNode = getSymNode(symbol);
+    if (symNode) {
+      const entity = program.checker.getTypeOrValueForNode(symNode);
+      if (entity && isType(entity)) {
+        type = entity;
+      }
     }
   }
   if (type) {

packages/compiler/src/server/type-signature.ts

@@ -46,7 +46,7 @@ export async function getSymbolSignature(
     case SyntaxKind.AliasStatement:
       return fence(`alias ${await getAliasSignature(decl)}`);
   }
-  const entity = sym.type ?? program.checker.getTypeOrValueForNode(decl);
+  const entity = sym.type ?? (decl ? program.checker.getTypeOrValueForNode(decl) : null);
   return getEntitySignature(sym, entity, options);
 }
 

packages/typespec-vscode/src/extension.ts

@@ -126,6 +126,13 @@ export async function activate(context: ExtensionContext) {
                 async (tel): Promise<ResultCode> => {
                   return await emitCode(context, uri, tel);
                 },
+                undefined,
+                (e) => {
+                  logger.error("Unexpected error when emitting code from TypeSpec.", [e], {
+                    showPopup: true,
+                  });
+                  return ResultCode.Fail;
+                },
               );
             },
           );
@@ -165,6 +172,14 @@ export async function activate(context: ExtensionContext) {
                     }
                   },
                   args?.activityId,
+                  (e) => {
+                    logger.error(
+                      "Unexpected error when restarting TypeSpec language server.",
+                      [e],
+                      { showPopup: true },
+                    );
+                    return { code: ResultCode.Fail };
+                  },
                 );
               },
             );
@@ -198,7 +213,26 @@ export async function activate(context: ExtensionContext) {
           await telemetryClient.doOperationWithTelemetry(
             TelemetryEventName.PreviewOpenApi3,
             async (tel): Promise<ResultCode> => {
-              return await showOpenApi3(uri, context, tspLanguageClient!, tel);
+              if (!tspLanguageClient || tspLanguageClient.state !== State.Running) {
+                logger.error(
+                  "TypeSpec language server is not running. Please restart the server.",
+                  [],
+                  { showPopup: true },
+                );
+                telemetryClient.logOperationDetailTelemetry(tel.activityId, {
+                  error: "LSP client is not running",
+                });
+                tel.lastStep = "Check LSP client";
+                return ResultCode.Fail;
+              }
+              return await showOpenApi3(uri, context, tspLanguageClient, tel);
+            },
+            undefined,
+            (e) => {
+              logger.error("Unexpected error when previewing OpenAPI3.", [e], {
+                showPopup: true,
+              });
+              return ResultCode.Fail;
             },
           );
         }),
@@ -213,6 +247,13 @@ export async function activate(context: ExtensionContext) {
               async (tel) => {
                 return await recreateLSPClient(context, tel.activityId);
               },
+              undefined,
+              (e) => {
+                logger.error("Unexpected error when restarting server after path change.", [e], {
+                  showPopup: true,
+                });
+                return { code: ResultCode.Fail };
+              },
             );
           }
         }),
@@ -318,14 +359,30 @@ export async function activate(context: ExtensionContext) {
             return installResult.code;
           },
           tel.activityId,
+          (e) => {
+            logger.error("Unexpected error when starting TypeSpec language server.", [e], {
+              showPopup: true,
+            });
+            return ResultCode.Fail;
+          },
         );
       } else {
         logger.info("No workspace opened, Skip starting TypeSpec language service.");
+        telemetryClient.logOperationDetailTelemetry(tel.activityId, {
+          compilerLocation: "skipped-no-workspace-or-tsp-file",
+        });
       }
       showStartUpMessages(stateManager);
       telemetryClient.sendDelayedTelemetryEvents();
       return ResultCode.Success;
     },
+    undefined,
+    (e) => {
+      logger.error("Unexpected error when starting TypeSpec extension.", [e], {
+        showPopup: true,
+      });
+      return ResultCode.Fail;
+    },
   );
 
   // Expose API for other extensions to consume
@@ -339,36 +396,52 @@ export async function activate(context: ExtensionContext) {
 }
 
 export async function deactivate() {
-  await tspLanguageClient?.stop();
-  await clearOpenApi3PreviewTempFolders();
+  try {
+    await tspLanguageClient?.stop();
+    await clearOpenApi3PreviewTempFolders();
+  } catch (e) {
+    logger.error("Error during extension deactivation", [e]);
+  }
 }
 
 async function recreateLSPClient(
   context: ExtensionContext,
   activityId: string,
 ): Promise<Result<TspLanguageClient>> {
-  logger.info("Recreating TypeSpec LSP server...");
-  const oldClient = tspLanguageClient;
-  setTspLanguageClient(await TspLanguageClient.create(activityId, context, outputChannel));
-  await oldClient?.stop();
-  if (!tspLanguageClient) {
-    telemetryClient.logOperationDetailTelemetry(activityId, {
-      error: "Failed to create TspLanguageClient",
-    });
-    return { code: ResultCode.Fail, details: "Failed to create TspLanguageClient." };
-  } else {
-    await tspLanguageClient.start(activityId);
-    if (tspLanguageClient.state === State.Running) {
+  try {
+    logger.info("Recreating TypeSpec LSP server...");
+    const oldClient = tspLanguageClient;
+    setTspLanguageClient(await TspLanguageClient.create(activityId, context, outputChannel));
+    await oldClient?.stop();
+    if (!tspLanguageClient) {
       telemetryClient.logOperationDetailTelemetry(activityId, {
-        compilerVersion: tspLanguageClient.initializeResult?.serverInfo?.version ?? "< 0.64.0",
+        error: "Failed to create TspLanguageClient. Compiler could not be resolved.",
       });
-      return { code: ResultCode.Success, value: tspLanguageClient };
+      return { code: ResultCode.Fail, details: "Failed to create TspLanguageClient." };
     } else {
-      telemetryClient.logOperationDetailTelemetry(activityId, {
-        error: `Failed to start TspLanguageClient.`,
-      });
-      return { code: ResultCode.Fail, details: "TspLanguageClient is not running." };
+      await tspLanguageClient.start(activityId);
+      if (tspLanguageClient.state === State.Running) {
+        telemetryClient.logOperationDetailTelemetry(activityId, {
+          compilerVersion: tspLanguageClient.initializeResult?.serverInfo?.version ?? "< 0.64.0",
+        });
+        return { code: ResultCode.Success, value: tspLanguageClient };
+      } else {
+        telemetryClient.logOperationDetailTelemetry(activityId, {
+          error: `Failed to start TspLanguageClient. State: ${tspLanguageClient.state}`,
+        });
+        return { code: ResultCode.Fail, details: "TspLanguageClient is not running." };
+      }
     }
+  } catch (e) {
+    logger.error(
+      "TypeSpec language server is unavailable due to an unexpected error. Please restart the server.",
+      [e],
+      { showPopup: true },
+    );
+    telemetryClient.logOperationDetailTelemetry(activityId, {
+      error: `Unexpected error in recreateLSPClient: ${e}`,
+    });
+    return { code: ResultCode.Fail, details: `Unexpected error: ${e}` };
   }
 }
 

packages/typespec-vscode/src/telemetry/telemetry-client.ts

@@ -120,6 +120,13 @@ export class TelemetryClient {
       sendTelemetryEvent: (result: ResultCode, delay: boolean) => void,
     ) => Promise<T>,
     activityId?: string,
+    /**
+     * Optional callback to handle unhandled exceptions from the operation.
+     * If provided, the exception will NOT be re-thrown and this callback will be invoked instead,
+     * and its return value will be used as the result of the operation.
+     * If not provided, the exception will be re-thrown after telemetry logging (default behavior).
+     */
+    onUnhandledException?: (error: unknown) => T,
   ): Promise<T> {
     const opTelemetryEvent = this.createOperationTelemetryEvent(eventName, activityId);
     let eventSent = false;
@@ -149,6 +156,9 @@ export class TelemetryClient {
         error: "Unhandled exception from operation to doOperationWithTelemetry: \n" + inspect(e),
       });
       opTelemetryEvent.result = ResultCode.Fail;
+      if (onUnhandledException) {
+        return onUnhandledException(e);
+      }
       // just report the issue in telemetry and re-throw the error
       throw e;
     } finally {

packages/typespec-vscode/src/telemetry/telemetry-event.ts

@@ -39,6 +39,7 @@ export enum OperationDetailPropertyName {
   emitResult,
   compilerLocation,
   compilerVersion,
+  compilerStartType,
   CompileStartTime,
   CompileEndTime,
 }