Troubleshooting

Common issues and solutions for GDSFactory+. Many issues can be diagnosed by checking the GDSFactory+ Output panel (View > Output > select "GDSFactory+") or by asking the AI agent.

Installation Issues - Extension not loading, API keys, missing dependencies
Python Environment Issues - Virtual environment, package, and import errors
Platform-Specific Issues - Windows and macOS quirks
Network Issues - Firewalls, proxies, and cloud workspaces
Component Issues - Build failures and DRC problems
Layout Viewer Issues - Blank viewer, rendering problems
Using GDSFactory+ Over SSH - Remote development setup
Getting More Help

Installation Issues¶

Extension Not Loading¶

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

Solutions:

Restart VSCode after installing the extension
Make sure you have opened a GDSFactory+ project folder (one with a pyproject.toml file)
Check the VSCode Output panel (View > Output) and select "GDSFactory+" from the dropdown for error messages

API Key Not Working¶

Symptoms: "Invalid API key" or authentication errors.

Solutions:

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

UV Not Found¶

Symptoms: Error message about uv not being installed.

Solutions:

Install uv by following the official installation guide
Restart VSCode after installation
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:

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

Wrong Python Version¶

Symptoms: Syntax errors or incompatible package errors on startup.

Solutions:

GDSFactory+ requires Python 3.12. Check your version:
```
python --version
```
If using a different version, install Python 3.12 and recreate the virtual environment:
```
uv python install 3.12
uv sync
```

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

Network Issues¶

Firewall or Proxy Blocking Access¶

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

Solutions:

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

Cloud Workspace Not Loading¶

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

Solutions:

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

Component Issues¶

Components Not Building¶

Symptoms: Components are greyed out or show build errors.

Solutions:

Click the play button at the top of the Components menu to trigger a build
Check the Output panel for error messages
Check GDSFactory logs for build errors
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:

Make sure you have the correct PDK configured in pyproject.toml
Check that the component GDS file exists and is valid
Review the timeout setting in your configuration. If your design is large, you may need to increase the timeout value.
Check the Output 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:

Restart the GDSFactory+ server: open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run "GDSFactory+: Restart Server"
Check that the server is running by looking at the Output panel for "GDSFactory+"
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:

Make sure the file watcher is running — check the Output panel for watcher activity
Save the file (the watcher triggers on save, not on edit)
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:

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

Setup¶

1. Install the Remote-SSH Extension¶

In VSCode on your local machine:

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

2. Connect to Your Remote Server¶

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

Tip: To add a host for easier future connections:

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

3. Open a Project on the Remote Server¶

Once connected to the remote server:

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

Alternatively, clone a project directly on the remote server:

Open the integrated terminal (Ctrl+` or View → Terminal)

Clone the project:

git clone https://github.com/gdsfactory/gdsfactory_sample_project

Open the cloned folder via File → Open Folder

4. Install GDSFactory+ on the Remote Machine¶

When you first open a GDSFactory+ project:

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

You can also manually install it:

Open Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
Search for "GDSFactory+"
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:

Open the VSCode Ports panel (View → Ports, or click "Ports" in the bottom panel)
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:

Open the VSCode Ports panel
Click Forward a Port
Enter the server port shown in the GDSFactory+ output log