Remote Workspaces
Remote Workspaces – Troubleshooting
Diagnose and resolve common problems when creating, connecting to, or working inside a remote workspace
Even the smoothest remote workspace can hit a snag. This guide walks you through the quickest fixes for the most common remote workspace issues.
Quick Reference
| Category | Typical Symptoms |
|---|---|
| Workspace Creation | “Provisioning” forever, cloning errors, devcontainer upload fails |
| Connection | Can’t attach from session, pairing spinner never stops, “Machine unavailable” |
| Performance | Slow rebuilds, high latency in terminal, laggy editor |
| Devcontainer | Build errors, “command not found”, ports not reachable |
| General Usage | Git asks for credentials, disk full, permission denied |
1. Workspace Creation Issues
Repository clone failed
Repository clone failed
Diagnose
- Error toast shows “clone failed” with a Git exit code
- Private repo? Missing OAuth scopes?
- Verify the repo is enabled and displays Connected in Integrations
- Refresh your OAuth token if prompted
Devcontainer upload error
Devcontainer upload error
Diagnose
- Upload modal closes with “Failed to save devcontainer”
- File larger than 1 MB or not JSON?
- Confirm file is named devcontainer.json and under 1 MB
- Validate JSON with an online linter
- Re-upload and click Create Workspace
2. Connection Problems
1
Check Machine Selector
In your session, click the CPU icon → ensure Cloud Machine is selected.
If it shows Local Machine, switch to Cloud Machine and pick the workspace.
If it shows Local Machine, switch to Cloud Machine and pick the workspace.
2
Browser & Network
- Use Chrome or Edge (other browsers may block WebSocket upgrades).
- Disable VPN/proxy to rule out WebSocket filtering.
- Reload the session tab (⌘R / Ctrl-R).
3. Performance & Speed
| Symptom | Fix |
|---|---|
| Rebuild takes > 5 min | Add .dockerignore for node_modules, *.pyc, build outputs• Use a lighter base image (e.g., alpine) |
| Terminal latency | Close unused browser tabs with heavy JS• Check local bandwidth (>5 Mbps recommended)• Pause real-time spell-checker extensions |
| Editor lag | Disable file watchers in dev tools (nodemon, webpack --watch) unless needed• Use auto-save only when collaborating |
4. Devcontainer Configuration Errors
Build fails with 'command not found'
Build fails with 'command not found'
Diagnose – The failing command runs inside
postCreateCommand.Resolve- Ensure the binary is installed earlier in the image or via your package manager (
apt-get,npm,pip). - Rebuild locally:
devcontainer up —workspace-folder .
Fix until it succeeds, then push changes and rebuild the workspace.
Environment variable undefined
Environment variable undefined
Diagnose – Script prints blank when echoing
$MY_SECRET.Resolve- Check Integrations → Secrets for correct name and value.
- Redeploy the workspace (hibernating won’t reload new secrets).
- Avoid exporting secrets during image build; read them at runtime.
5. General Usage Troubles
| Issue | Resolution |
|---|---|
| Git prompts for credentials | Make sure the repo integration is connected; remote workspace injects HTTPS tokens automatically. |
| Disk quota exceeded | Clear package caches (npm cache clean --force, pip cache purge), remove large build artifacts, or rebuild workspace. |
| Permission denied on file save | File is outside the repo workspace; save inside /workspaces/<repo>/. |
| Cannot install global packages | Use npm install -g or pip install --user. If still blocked, add commands to postCreateCommand. |
| History lost after rebuild | Anything outside /workspaces is cleared during rebuild. Commit important scripts or store them inside the repo. |
Need More Help?
- Docs – Review Configure Your Devcontainer
- Best Practices – Optimize performance with the Remote Workspace Best Practices guide
- Support – Reach out in your Factory support channel with workspace ID and error message
A quick rebuild fixes 80 % of issues—don’t hesitate to click Rebuild when in doubt.