Troubleshooting your codespace

Use this guide to help you troubleshoot common issues with your codespace.

In this article

Note: Codespaces is currently in limited public beta and subject to change. For more information about joining the beta, see "About Codespaces."

Known Limitations

During the beta, functionality is limited.

  • For the best experience with Codespaces, we recommend using a Chromium-based browser, like Google Chrome or Microsoft Edge.
  • Only a single size of codespace is available.
  • Only Linux containers are supported.
  • A codespace is not fully resumable. Processes that were running at the time the codespace was stopped will not be restarted.

During the beta, private repositories owned by organizations or any repositories owned by an organization that requires SAML single sign-on are not supported.

Visual Studio Code troubleshooting

Use Issues in the microsoft/vscode repository to check for known issues or to log issues about the Visual Studio Code experience.

Configuration troubleshooting

If changes to your codespace's configuration cause a container error, your codespace will run in recovery mode, and you will see an error message.

This codespace is currently running in recovery mode due to a container error.

Review the creation logs, update the configuration as needed, and run Codespaces: Rebuild Container in the command palette to retry. For more information, see "Configuring Codespaces for your project."

dotfiles troubleshooting

  • Make sure your dotfiles repository is public. If you have secrets or sensitive data you want to use in your codespace, use Codespace secrets instead of private dotfiles.
  • Check /workspaces/.codespaces/.persistedshare/dotfiles to see if your dotfiles were cloned.
    • If your dotfiles were cloned, try manually re-running your install script to verify it's executable.
    • If your dotfiles weren't cloned, check /workspaces/.codespaces/.persistedshare/EnvironmentLog.txt to see if there was a problem cloning them.
  • Check /workspaces/.codespaces/.persistedshare/creation.log for possible issues. Alternatively, you can view the creation.log by navigating to the command palette and entering Codespaces: View Creation Log.

Browser troubleshooting

If you encounter issues while using a browser that is not Chromium-based, try switching to a Chromium-based browser, or check for known issues with your browser in the microsoft/vscode repository by searching for issues labeled with the name of your browser, such asfirefox or safari.

If you encounter issues while using a Chromium-based browser, you can check if you're experiencing another known issue with Visual Studio Code in the microsoft/vscode repository.

Container storage troubleshooting

When you create a codespace, it has a finite amount of storage and over time it may be necessary for you to free up space. Try any of the following items to free up storage space.

  • Remove packages that are no longer by using sudo apt autoremove
  • Clean the apt cache by using sudo apt clean
  • Delete unneeded files like build artifacts and logs (these are very project-dependent)
  • See the top 10 largest files in the codespace: sudo find / -printf '%s %p\n'| sort -nr | head -10

More destructive options:

  • Remove unused Docker images, networks, and containers by using docker system prune (append -a if you want to remove all images, and --volumes if you want to remove all volumes)
  • Remove untracked files from working tree: git clean -i

Contact us

If you still need help, you can contact us. For more information, see "About Codespaces."

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.