Project IDX troubleshooting & FAQ

Tip: If you don't find an answer to your question, ask it in our community forums, file a bug or a feature request.

While opening a workspace, I see the message Unable to forward your request to backend. Couldn't connect to a server on port 80.

This is a known issue. As a workaround, wait approximately 5 seconds and refresh the page.

My preview is broken, but I see nothing wrong with my code. How can I restart IDX ?

If IDX isn't refreshing properly (typically as a result of major refactors, or changes to the monospace.json file), perform a Hard Restart, available in the command palette (Cmd+Shift+P on Mac or Ctrl+Shift+P on ChromeOS, Windows, or Linux), under the IDX category.

While creating a workspace, I see a message, Whoops.. We need to spin up a new VM, and the UI hangs after that

IDX maintains a warm pool of VMs used to provision workspaces on demand. When the pool runs low, the workspaces are provisioned after a new VM is spun. The process can take time (sometimes up to 5 minutes) but eventually succeeds.

While creating a workspace, I see a message, an internal error occurred

In most cases of internal errors during workspace provisioning, refreshing the page after a minute or so should get you past the error and into the workspace.

How many different workspaces can I have on my account?

IDX has a limit of 1 workspace per user. If you have a Google Developer Profile, you can create up to 5 workspaces. To create a Google Developer Profile directly from IDX once you've hit the workspace limit, click Complete Setup from the notification on the template dashboard.

My workspace loads but the emulator is blank

We're actively improving the reliability of our cloud-based emulators. If a page refresh does not fix the problem, please report the issue.

IDX workspaces have a Flutter version that is incompatible with my project.

You can upgrade or downgrade the version of almost all preinstalled software inside a workspace like you would on your local machine (using apt-get or brew). Note that the changes are not preserved when an "idle" workspace hibernates.

What's the difference between Project IDX and Google Cloud Workstations?

We've built IDX on the (incredible!) generally available Cloud Workstations offering from Google Cloud. Cloud Workstations is an infrastructure offering that focuses on developer workstations' reliability, security, and availability. It's the ideal choice for large enterprises that want to manage their development experience. Project IDX is a "batteries included" environment inside these workstations that manages the toolchains, software development stack, and system dependencies required to build different application types.

I am unfamiliar with Linux. How do I become productive on Project IDX?

Project IDX exposes a Debian shell that you can use to install and manage system-level software dependencies of your project. We're soon moving to an OS-agnostic, Nix-based shell that you can use to manage system software dependencies as configurations without understanding the specifics of OS-specific package managers like apt. Stay tuned!

Why does IDX need third-party (3P) cookies enabled?

IDX needs 3P cookies enabled since we render an IFRAME from one domain (a subdomain of cloudworkstations.dev) on another domain (idx.google.com), and 3P cookies enable secure cross-origin communication.

I shared my workstation URL with someone, but they cannot see my workspace

You can only share a workspace URL with users that have access to the workspace. Users without permission see an error when trying to visit the URL. Be sure to explicitly share the workspace with them, like sharing a Google Doc!

When I share my workstation, what can my collaborator see?

Users added to your workspace have complete access to the VM's entire filesystem, which may contain sensitive files like private keys and access tokens. Share your workspace only with people you trust. While this approach helps other users view the exact state of your workspace, it means that they see everything on your workspace.

How can I safely share my workspace that has my Firebase credentials?

When you use IDX to deploy your applications to Firebase, the workspace is provisioned with only the most basic permissions required to perform the operations. While you, as a user, may be an administrator of your project, the workspace itself doesn't have all the permissions that come with being an owner, operating on the principles of least privilege.

Can I use frameworks that IDX does not support to build my application?

Yes! While we're working on allowing workspaces to be fully customizable, it is entirely possible to import your projects that use an unsupported frontend framework or may not have a UI at all. The simplest way to get past this would be to select Other as the App Type in the Import a repo flow. Once you've set up your workspace, you can install any system-level dependencies your project needs.

Can I import my repo from GitLab or Cloud Source repos?

At the moment, we support GitHub. If you want us to support more Git hosts, submit a feature request.

In the meantime, you can create a new workspace from an existing template and run git clone with any https or ssh-based Git host in a terminal, like you normally would on your local machine.

What target directory should I select when deploying a Flutter app to Firebase Hosting?

Choose the build/web directory. This directory should contain an index.html and all the static assets needed to render your web app after the app is built successfully (via flutter build web).

How can I set up my app's backend on my workspace so that my frontend can speak to it?

We plan to simplify this in the near future, but for now, use the following workaround:

1. Projects that have an API backend can start their API services either manually in a terminal, or configure the startup command in the monospace.json file.

2. Open the port on which the API service runs to be accessible to your web frontend preview by running the following bash script in a terminal:

   export port=4000 #dont use restricted ports (8000, 9000-9002)
   export API_SERVICE="https://$port-$WEB_HOST"
   echo $API_SERVICE
   

3. Open the API_SERVICE URL above a new tab in your browser. This sets a required cookie through a redirect flow.

4. Your web app frontend can now access the API service at the fully qualified path.

I closed my preview tab. How do I bring it back?

Open the command palette (Cmd+Shift+P on Mac or Ctrl+Shift+P on ChromeOS, Windows, or Linux) and select Project IDX: Show Web Preview.

What is Code OSS?

Code-Open Source Software (Code-OSS) is an open-source project that's the core layer of VS Code. Code-OSS is available on GitHub under the standard MIT License, and is where Microsoft develops the VS Code product.

How can I prevent my code completions and Gemini chat prompts from being used as training data?

If you don't want your Gemini chat prompts used as training data to improve Gemini in IDX, don't use the chat assistant and turn off code completion in your workspace Settings. You can also turn off assistance when working with specific files by adding .aiexclude file(s) to your repository.

How do I submit a feature request or feedback on an issue I encountered?

If you encounter an issue while using Project IDX, file a bug to let us know.

If there's a feature you want to see added to IDX, or an existing feature you want expanded, file a feature request.

IDX uses IssueTracker for bugs and feature requests, to support robust requests with screenshots and video. In the future, IDX will likely track feedback and features through UserVoice. Any feedback or requests already submitted through UserVoice have been preserved and shared with the team.

How can I find out if Gemini in IDX is available in my country or region?

Gemini in IDX is available in limited regions, with availability expanding regularly. If Gemini in IDX is available in your region, you can add it to your workspace following the steps outlined in Add Gemini to your workspace.

I was using a particular feature in Project IDX but I can't find it anymore. Why was it removed?

Some of the features in Project IDX are experimental. We value your feedback and actively use it to inform our current and planned feature set, periodically removing features that aren't living up to your expectations or our own. If there are features you'd like to see in your ideal version of Project IDX, send us feedback. We want to hear from you!