Embedded GitHub project gets stuck on "Cloning repo from GitHub" / "Mounting environment" after recent repo changes

[veigap]

Description

When embedding a StackBlitz project from a GitHub repository using the SDK (sdk.connect(iframe)), the embed frequently gets stuck at the "Cloning repo from GitHub" / "Mounting environment in StackBlitz" phase and never progresses. This particularly happens after the repository has been recently updated (e.g., dependency upgrades, new commits).

Steps to Reproduce

1. Embed a GitHub project using an iframe URL like:

   https://stackblitz.com/github/{org}/{repo}?file=src/example.ts&embed=1&view=editor
   

2. Connect via the SDK:

   const sdk = await import('@stackblitz/sdk');
   const vm = await sdk.connect(iframe);

3. Push a change to the GitHub repository (e.g., update dependencies)
4. Reload the page containing the embed

Expected Behavior

The embed should clone the latest version of the repository and mount the environment within a reasonable time.

Actual Behavior

The embed gets stuck indefinitely on "Cloning repo from GitHub" with "Mounting environment in StackBlitz" never completing. The WebSocket connection to wss://stackblitz.com/cable fails repeatedly in the console:

WebSocket connection to 'wss://stackblitz.com/cable' failed:
WebSocket connection to 'wss://stackblitz.com/cable' failed:

Additionally, the following console warnings appear (minor, but related):

Unrecognized feature: 'ambient-light-sensor'
Unrecognized feature: 'vr'

Environment

• Browser: Chrome (latest)
• OS: macOS
• SDK: @stackblitz/sdk (UMD bundle via unpkg)
• Embed method: iframe with sdk.connect()

Workaround

We implemented a client-side workaround that:

1. Races sdk.connect() against a 30-second timeout
2. After connection, polls vm.getFsSnapshot() for package.json to verify the repo actually cloned (since connect() can resolve even when StackBlitz is stuck mounting)
3. Shows a retry button that remounts the iframe if loading fails

const vm = await Promise.race([
  sdk.connect(iframe),
  new Promise((_, reject) =>
    setTimeout(() => reject(new Error('connect timeout')), 30000)
  )
]);

// Verify repo actually cloned
for (let i = 0; i < 15; i++) {
  try {
    const files = await vm.getFsSnapshot();
    if (files && files['package.json']) break;
  } catch (_) {}
  await new Promise(r => setTimeout(r, 2000));
}

Related Issues

• Trying to open GitHub repo in StackBlitz never completes, gets stuck then crashes  core#2849 - Stuck on clone
• Preview is stuck on Booting webcontainer for github connected typescript blank project core#2847 - Stuck on boot
• Stuck on dev server when embedded (run), but forking works core#2850 - Stuck on embed
• Hanging on "INITIALIZING GIT REPOSITORY" core#1021 - Hanging on init

[veigap]

Source Code

The project experiencing this issue is open source. Here are direct links to the relevant code with the workaround implementation:

• CodeEditor component (full file): https://github.com/pluna/ai-tutorial/blob/main/snippets/CodeEditor.jsx
• Timeout + FS polling workaround: https://github.com/pluna/ai-tutorial/blob/main/snippets/CodeEditor.jsx#L378-L460
• Retry handler (remounts iframe): https://github.com/pluna/ai-tutorial/blob/main/snippets/CodeEditor.jsx#L391-L396
• Stuck overlay UI: https://github.com/pluna/ai-tutorial/blob/main/snippets/CodeEditor.jsx#L720-L745

Feel free to look at the full implementation for context.

[veigap]

The project is live at https://aitutorial.dev — the StackBlitz embeds are used throughout the site for interactive code examples. The stuck loading behavior can be reproduced on any page with a CodeEditor component after the underlying GitHub repo receives a new commit.

[veigap]

Additional Observation: Filesystem Not Properly Mounted

When the embed gets stuck, the WebContainer filesystem is not properly mounted. Calling vm.getFsSnapshot() after sdk.connect() resolves returns either null or an incomplete/empty file tree — even though the StackBlitz UI shows "Cloning repo from GitHub" as if it's in progress.

This confirms that sdk.connect() can resolve successfully before the filesystem is ready, making it unreliable as a signal that the project has loaded. Our workaround polls getFsSnapshot() for the presence of package.json to detect this state.

[veigap]

Error Output When Filesystem Mount Fails

When the WebContainer filesystem fails to mount properly, the terminal shows:

The environment initialization appears to be corrupted.
Please reload the page to reinitialize the environment.

✗ Error: Failed to read config file: Config file not found: env/run.conf

This happens because our startup script (run.sh) expects files that were supposed to be written via vm.applyFsDiff() after connecting, but the filesystem was never properly initialized. The project's own files (cloned from GitHub) are also missing — package.json, tsconfig.json, etc. are not present in the WebContainer filesystem.

This further confirms the root cause: sdk.connect() resolves before the GitHub clone completes, leaving the WebContainer in a broken state with an empty/corrupted filesystem.