Application Note - VS Code Empty Webviews

VS Code Empty Webviews

DVT IDE for VS Code presents structured data in several views such as Compile Order, Verification and Design Hierarchies, UVM Registers, Config DB, Factory Overrides and Inspect. They are implemented as “webviews”, a commonly used platform for building custom UIs in VS Code extensions.

When a webview (whether provided by DVT or any other extension that relies on webviews) appears empty, the underlying cause is usually the same: a bug in VS Code triggered by an unsupported execution environment or by multiple VS Code processes competing for the same user-data resources. This application note presents the symptoms, causes, and steps to resolve the issue, depending on your setup.

What you see

To quickly check if the issue appears on your side, inspect the following:

  • DVT views (e.g., Compile Order, Design / Verification Hierarchy, Inspect View, etc…) are empty.

../../../_images/webviews-examples.png

  • An error pop-up appears in the bottom right corner / Notification Center: Error loading webview: Error: Could not register service worker: InvalidStateError: Failed to register a ServiceWorker: The document is in an invalid state.

../../../_images/error-loading-webview.png

Restarting VS Code is not sufficient to fix the issue.

Why does this happen?

This behavior is caused by a known VS Code bug affecting webview initialization and service worker registration. The issue has been reported in multiple tickets, including the following Github ticket.

There are several scenarios known to cause the problem:

  • Multiple VS Code instances: Running several VS Code processes (e.g., via LSF, or similar, on a compute farm) causes conflicts.

  • Running VS Code on multiple machines: Running different VS Code processes on multiple machines under the same user with shared home directories.

  • Version mismatches: Launching multiple instances with different VS Code versions at the same time.

  • Unsupported environments: VS Code explicitly does not support (Official VS Code docs):

    • Multiple simultaneous users on the same machine (e.g., shared VDI or pooled hosts).

    • Non-persistent VMs, app virtualization, or containers for the full VS Code.

The root cause of the issue arises from the way VS Code operates.

The first VS Code instance is considered the master process. It locks the user data directory (henceforth, referred to as ${VSCODE_USER_DATA_DIR}. Default location: ${HOME}/.config/Code, can be customized using the –user-data-dir VS Code flag). Subsequently launched VS Code processes will reparent themselves under the master process and share the same user data directory.

Tip

Application

Default user data directory

VS Code

${HOME}/.config/Code

VSCodium

${HOME}/.config/VSCodium

Cursor

${HOME}/.config/Cursor

Windsurf

${HOME}/.config/Windsurf

Antigravity

${HOME}/.config/Antigravity

There are many VS Code forks available. If yours is not present in this table, please consult its documentation for the default user data directory location.

The issue is more common when running on multiple machines, (such as when running in LSF) because instances of VS Code landing on different hosts cannot communicate with each other and find the master process. This results in each one considering themselves as master and trying to acquire the user directory lock. While only one will be able to do so, the rest will experience the empty webview issue.

How to fix the issue

Since this is a VS Code bug, extensions cannot fully recover from it programmatically. However, the following fixes are known to resolve the issue.

First of all, regardless of your setup:

  1. Close all Code instances running under your username.

  2. Ensure no background processes remain:

killall code # or codium / cursor / … other VS Code forks
bkill <jobId> # if using LSF

Warning

If a single process of Code is still running, the following fixes won’t work!

Next, check below the available solutions:

Solution 1: Remove part of the user data directory

  1. Remove the internal database:

rm -rf ${VSCODE_USER_DATA_DIR}/User/globalStorage/state.vscdb

  1. Restart the application.

Warning

Removing the state.vscdb will also remove any OAuth tokens, triggering a re-authentication at next startup(e.g, Copilot, Cursor’s login screen).

Solution 2: Create a new user data directory

  1. Start Code using a custom --user-data-dir:

code --user-data-dir /path/to/new/user/data

Warning

Creating a new user data directory will start a fresh instance of Code without any of your global preferences, OAuth tokens, profiles, keybindings, etc…

Solution 3: Create a shallow copy of the user data directory (only for DVT Kit Distro)

  1. Start VSCodium using -enable_process_separation:

dvt_code.sh createProject /path/to/project -lang VLOG -enable_process_separation

For each new window, a new shallow copy of your user data directory will be created in your /tmp folder, avoiding the resource contention. The copy will keep your preferences, snippets, and keybindings in sync across all sessions. However, it will not have access to your OAuth tokens,so you will have to re-authenticate each time you start a new instance of VSCodium (for example if using Copilot or Cursor).

Best practices

To prevent the issue from recurring:

  • Do not start multiple VS Code instances across different machines that share the same home directory.

  • Avoid mixing different VS Code versions.

  • Do not launch full VS Code sessions via job schedulers such as LSF. Instead, run VS Code UI locally and dispatch only the DVT Language Server to the farm. To achieve this, go to the Settings Page and update the DVT.languageServer.launchCommand preference:

"DVT.languageServer.launchCommand": "bsub <bsub_args> ${LS_LAUNCH_CMD}"