Quick Reference
| Category | Typical Symptoms |
|---|---|
| Workspace Creation | “Provisioning” forever, cloning errors, custom commands 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
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. 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?
- 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.