Skip to content

Troubleshooting

Common issues and solutions for GDSFactory+. Many issues can be diagnosed by checking the GF+ Logs panel (Command Palette → GDSFactory+: Open GF+ Logs) or the build/extension.log file, or by asking the AI agent.

Quick Navigation

Installation Issues

Extension Not Loading

Symptoms: The GF+ icon doesn't appear in the sidebar, or the extension panel is empty.

Solutions:

  1. Restart VSCode after installing the extension
  2. Make sure you have opened a GDSFactory+ project folder (one with a pyproject.toml file)
  3. Check the GF+ Logs panel (Command Palette → GDSFactory+: Open GF+ Logs) for error messages

API Key Not Working

Symptoms: "Invalid API key" or authentication errors.

Solutions:

  1. Verify your API key is correct at plus.gdsfactory.com under API Keys
  2. Check that the key is properly saved in your settings file:
    • macOS/Linux: ~/.gdsfactory/gdsfactoryplus.toml
    • Windows: C:\Users\<YourUsername>\.gdsfactory\gdsfactoryplus.toml
  3. Generate a new API key if the current one isn't working

Low-Memory Warning

Symptoms: A warning notification appears at startup about available memory.

Solution: You can continue using GDSFactory+ and click Dismiss warning forever to suppress future warnings. See System Requirements for recommended RAM.

UV Not Found

Symptoms: Error message about uv not being installed.

Solutions:

  1. Install uv:

    • Windows (PowerShell):

      mkdir "$env:USERPROFILE\.gdsfactory\uv"
$env:UV_UNMANAGED_INSTALL = "$env:USERPROFILE\.gdsfactory\uv"
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

    • Mac/Linux: run curl -LsSf https://astral.sh/uv/install.sh | sh or wget -qO- https://astral.sh/uv/install.sh | sh.

      If neither works, install Homebrew first, then brew install uv.

  2. Restart VSCode after installation

  3. Verify installation by running uv --version in the terminal

Python Environment Issues

Virtual Environment Not Created

Symptoms: Import errors, "module not found" messages, or the server fails to start.

Solutions:

  1. Open a terminal in your project directory and run: 
    uv sync
  2. Verify the .venv directory exists in your project folder
  3. Check that pyproject.toml is present and correctly configured

Worker Health: Package Conflict

Symptoms: Worker Health shows a uv resolution failure or a package at an incompatible version (for example, your PDK pins gdsfactoryplus<2.0).

Solution: Click Add runtime overrides in the Status section. This writes compatible version constraints to pyproject.toml and re-runs uv sync without a window reload.

Worker preparation adds a managed SDK constraint to pyproject.toml and updates uv.lock. For uv workspace members, these are the workspace-root files, which may be above the folder opened in GF+. The first preparation may need package index access unless uv can resolve from local sources or its cache; unchanged, compatible locks are reused. If locking fails, an existing environment whose required runtime packages are already compatible can still build, with a warning in the server log. Persistence remains unresolved, so a later sync may downgrade the SDK; cold or incompatible environments still fail setup. Wait for automatic repair to finish before editing these files, since edits saved during preparation may be reverted if repair fails.

Wrong Python Version

Symptoms: Syntax errors or incompatible package errors on startup.

Solutions:

  1. GDSFactory+ requires Python 3.12 (3.12.0 or newer, below 3.13). Check your version: 
    python --version
  2. If using a different minor version, install a supported Python and recreate the virtual environment: 
    uv python install 3.12.14
uv sync
    We recommend 3.12.14 or newer for the latest security fixes — this matters most in offline or air-gapped environments where you can't easily update Python after the fact.

Platform-Specific Issues

Windows

Recommendation: For the best experience on Windows, install WSL (Windows Subsystem for Linux).

Common Windows issues:

  • Path issues: Use forward slashes (/) in paths or escape backslashes (\\)
  • Permission errors: Run VSCode as Administrator if you encounter permission issues
  • Long path errors: Enable long paths in Windows settings

macOS

  • Xcode required: Make sure Xcode is installed

Linux

Schematic Editor or Layout Viewer Blank (WebGL Not Available)

Symptoms: The schematic (Livewire) editor or the layout viewer opens but stays blank, or the GF+ Logs panel reports that WebGL is not available or "WebGL is not supported." This is most commonly seen on Debian and Ubuntu-based distributions, especially inside virtual machines.

Both editors render through WebGL. If VSCode's GPU stack can't provide a WebGL context, the canvas never paints.

Chromium's GPU blocklist disables WebGL on many Linux GPU and driver combinations. Passing the flags once from the command line confirms whether this is the problem:

code --enable-webgl --ignore-gpu-blocklist

To make the change permanent, add the same switches to VSCode's runtime arguments file so that they apply however you launch the editor:

  1. Open the Command Palette (Ctrl+Shift+P) and run Preferences: Configure Runtime Arguments. This opens argv.json (~/.vscode/argv.json, or ~/.vscode-oss/argv.json for VSCodium).

  2. Add:

    {
  "enable-webgl": true,
  "ignore-gpu-blocklist": true
}

  3. Fully quit and restart VSCode. Closing the window is not enough.

To confirm the result, open the Command Palette and run Developer: Toggle Developer Tools, then check the chrome://gpu-style status in the console. WebGL should report as hardware or software accelerated rather than disabled.

Solution 2 - Running Inside a VM

If you are using a virtual machine, the virtual GPU is usually the problem. Check which renderer is in use:

glxinfo | grep renderer

If it reports virgl or SVGA3D, either disable 3D acceleration in the VM settings or force software rendering:

LIBGL_ALWAYS_SOFTWARE=1 code

If the canvas is still blank, also add the SwiftShader fallback:

code --enable-unsafe-swiftshader

Expect rendering to be noticeably slower under software rendering. This is expected inside a VM, not a bug.

When reporting a Linux issue, include your distribution and version or codename (for example, "Debian 12 bookworm" or "Ubuntu 24.04"), whether you are on bare metal or a VM, and the output of glxinfo | grep renderer. "Linux" or "Debian" alone is not enough information to reproduce the issue.

Network Issues

License Check URL and Port

License validation sends a GET request to https://api.gdsfactory.com/api/verify-api-key, with your API key in the x-api-key header. Allow outbound HTTPS traffic to api.gdsfactory.com on TCP port 443 through your firewall or proxy.

To check API connectivity, open https://api.gdsfactory.com/api/portal/health in your browser. This health endpoint also uses HTTPS port 443. A successful health response confirms connectivity to that endpoint; license validation still requires access to /api/verify-api-key and a valid API key.

The API host can be overridden with api.host in your settings. If you configure an alternate host or an explicit port, allow traffic to that destination instead.

Firewall or Proxy Blocking Access

Symptoms: Timeouts, connection errors, or features not loading.

Solutions:

  1. Ensure your firewall allows connections to GDSFactory+ servers
  2. If behind a corporate proxy, configure VSCode to use your proxy settings
  3. Try temporarily disabling VPN if you're using one

VPN or Corporate Network Blocking API Access

Symptoms: GDSFactory+ cannot reach the API, license checks fail, or features that require server communication time out — even though general internet access works.

Solutions:

  1. Switch to a mobile network: Connect your computer to your phone's hotspot instead of the corporate network. This bypasses corporate firewalls and proxy restrictions that may block api.gdsfactory.com.
  2. Ask IT to whitelist the API: Request your IT department to allow outbound HTTPS traffic to api.gdsfactory.com on TCP port 443 through the corporate firewall or proxy. See License Check URL and Port for the endpoint and custom API host settings.

Cloud Workspace Not Loading

Symptoms: Workspace link doesn't work or shows an error.

Solutions:

  1. Wait a minute for the workspace to fully initialize
  2. Check the Docker logs in the Customer Portal for error details
  3. Try creating a new workspace if the issue persists

Component Issues

Components Not Building

Symptoms: Components are greyed out or show build errors.

Solutions:

  1. Click the play button at the top of the Components menu to trigger a build
  2. Check the GF+ Logs panel for error messages
  3. Check GDSFactory logs for build errors
  4. Verify your PDK is correctly configured in pyproject.toml: 
    [tool.gdsfactoryplus.pdk]
name = "your_pdk_name"

DRC Not Running

Symptoms: DRC check doesn't complete or shows no results.

Solutions:

  1. Make sure you have the correct PDK configured in pyproject.toml
  2. Check that the component GDS file exists and is valid
  3. Review the timeout setting in your configuration. If your design is large, you may need to increase the timeout value.
  4. Check the GF+ Logs panel for specific error messages from the DRC engine

Layout Viewer Issues

Viewer Shows Blank or Doesn't Load

Symptoms: The layout viewer panel opens but shows a white/blank area or a loading spinner that never completes.

Solutions:

  1. Restart the GDSFactory+ server: open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run "GDSFactory+: Restart Server"
  2. Check that the server is running by looking at the GF+ Logs panel
  3. If using a VPN or proxy, it may interfere with the local WebSocket connection — try disabling it temporarily

Layout Not Updating After Code Changes

Symptoms: You edited your Python code but the viewer still shows the old layout.

Solutions:

  1. Make sure the file watcher is running — check the GF+ Logs panel for watcher activity
  2. Save the file (the watcher triggers on save, not on edit)
  3. Manually trigger a rebuild by clicking the play button in the Components panel

Using GDSFactory+ Over SSH

GDSFactory+ works with VSCode's Remote-SSH extension, allowing you to run the extension on a remote server while viewing layouts locally.

How It Works

When using VSCode Remote-SSH:

  1. The GDSFactory+ extension runs on the remote machine
  2. Communication between the extension and server happens locally on the remote machine
  3. VSCode automatically handles forwarding the webview content to your local machine

Setup

1. Install the Remote-SSH Extension

In VSCode on your local machine:

  1. Open the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
  2. Search for "Remote - SSH"
  3. Install the extension from Marketplace

2. Connect to Your Remote Server

  1. Press F1 (or Ctrl+Shift+P / Cmd+Shift+P) to open the Command Palette
  2. Type "Remote-SSH: Connect to Host" and select it
  3. Enter your SSH connection string: user@your-server.com
  4. Select the platform of the remote machine (Linux, macOS, or Windows)
  5. VSCode will open a new window connected to the remote server

Tip: To add a host for easier future connections:

  1. Open Command Palette and select "Remote-SSH: Add New SSH Host"
  2. Enter: ssh user@your-server.com
  3. Select a config file to save to (usually ~/.ssh/config)

3. Open a Project on the Remote Server

Once connected to the remote server:

  1. Click File → Open Folder
  2. Browse to your project folder on the remote machine (e.g., /home/user/my-gds-project)
  3. Click OK to open the folder

Alternatively, clone a project directly on the remote server:

  1. Open the integrated terminal (Ctrl+` or View → Terminal)
  2. Clone the project: 
    git clone https://github.com/gdsfactory/gdsfactory_sample_project
  3. Open the cloned folder via File → Open Folder

4. Install GDSFactory+ on the Remote Machine

When you first open a GDSFactory+ project:

  1. VSCode will prompt you to install recommended extensions on the remote server
  2. Click Install when prompted for GDSFactory+
  3. The extension will install and activate on the remote machine

You can also manually install it:

  1. Open Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
  2. Search for "GDSFactory+"
  3. Click Install in SSH: your-server

The extension should work automatically. VSCode handles port forwarding for the layout viewer.

Port Forwarding

GDSFactory+ uses two ports internally:

  • HTTP server port: Serves the layout viewer (random port in range 7000-9999)
  • WebSocket port: Extension communication (random port in range 7000-9999)

The ports are assigned randomly at startup to avoid conflicts with other applications.

VSCode Remote-SSH automatically forwards ports used by webviews, so the layout viewer should work without additional configuration.

Checking Forwarded Ports

To see which ports are being forwarded:

  1. Open the VSCode Ports panel (View → Ports, or click "Ports" in the bottom panel)
  2. You should see the GDSFactory+ server port listed and forwarded automatically

Manual Port Forwarding (if needed)

If the layout viewer doesn't load, you can manually forward ports:

  1. Open the VSCode Ports panel
  2. Click Forward a Port
  3. Enter the server port shown in the GF+ Logs panel

Troubleshooting Remote Connections

Layout viewer shows blank or error:

  • Check that the server ports are not blocked by a firewall on the remote machine
  • Verify port forwarding is active in the VSCode Ports panel
  • Restart the GDSFactory+ server using the command palette: "GDSFactory+: Restart Server"

Extension not activating:

  • Ensure you've opened a folder with a pyproject.toml file
  • Check the GF+ Logs panel for error messages
  • Verify the Python environment is correctly set up on the remote machine

Getting More Help

If these solutions don't resolve your issue:

  1. Ask the AI agent — describe your problem and it can help diagnose the issue. See AI Agent for details.
  2. Check the GF+ Logs panel — Command Palette → GDSFactory+: Open GF+ Logs for detailed logs and error messages
  3. Join the community — get help from other users on Slack
  4. Watch the tutorials — Video Tutorials cover common workflows step-by-step
  5. Review your setup — compare against the Local Installation or Cloud Setup guides