Troubleshooting

Previous

Common issues and solutions for GDSFactory+.

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 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:

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

UV Not Found

Symptoms: Error message about uv not being installed.

Solutions:

  1. Install uv by following the official installation guide
  2. Restart VSCode after installation
  3. Verify installation by running uv --version in the terminal

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
  • Permission errors: Grant VSCode access to the folders you're working with in System Preferences > Security & Privacy

Linux

  • Display issues: Ensure your display environment is properly configured for GUI applications
  • Permission errors: Check file and folder permissions, or try running with elevated privileges

Network Issues

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

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 Output panel for error messages
  3. Verify your Python code has no syntax errors

DRC Not Running

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

Solutions:

  1. Make sure you have the correct DRC rules configured in pyproject.toml
  2. Check that the component GDS file exists and is valid
  3. Review the timeout setting in your configuration

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. The Python backend server runs on the remote machine
  3. Communication between the extension and server happens locally on the remote machine
  4. 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 Microsoft

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 GDSFactory+ output log

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 Output panel for error messages
  • Verify the Python environment is correctly set up on the remote machine

Slow performance:

  • The layout viewer transfers data over the network; large layouts may take longer to load
  • Consider using a faster network connection or VPN with lower latency

Getting More Help

If these solutions don't resolve your issue:

  1. Join the GDSFactory Community Slack for community support
  2. Check the Video Tutorials for step-by-step guidance
  3. Review the Local Installation or Cloud Setup guides to verify your setup
Community