Why is my CDE connection slow?

Common causes include: high network latency to the workspace region, insufficient workspace resources, VS Code extension conflicts, or file sync issues. Try selecting a closer region, increasing workspace specs, or using Mutagen for file sync.

Why won't VS Code Remote SSH connect to my workspace?

Check: SSH key configuration, workspace is running (not stopped), firewall rules allow SSH, correct hostname/IP, and VS Code Remote SSH extension is updated. Review workspace logs for specific errors.

How do I debug workspace startup failures?

Check workspace build logs for container build errors, verify base image availability, ensure sufficient cluster resources, check for DevContainer configuration errors, and verify network connectivity to container registries.

CDE Troubleshooting Guide

Common issues and solutions for cloud development environments

Quick Diagnostics

coder ping

Test workspace connectivity

df -h

Check disk space

free -m

Check memory usage

nvidia-smi

Check GPU status

Connectivity Issues

Symptoms

- "Connection refused" error
- Timeout when connecting via SSH
- VS Code Remote shows "connecting..." forever

Causes

- Workspace stopped or failed to start
- Network/firewall blocking connection
- SSH agent not configured

Solution

1. Check workspace status in CDE dashboard - restart if stopped
2. Run coder config-ssh to refresh SSH config
3. Test with ssh -v coder.workspace-name for verbose output
4. Check if corporate VPN is blocking port 22 or the CDE domain

Prevention

Configure workspace auto-start, add CDE domains to VPN split-tunnel, set up SSH keepalive.

Symptoms

- Noticeable delay when typing
- Commands take seconds to execute
- IDE feels sluggish

Causes

- Workspace in distant region
- Network congestion or poor WiFi
- VPN routing all traffic

Solution

1. Run ping workspace-url to check latency (target: <50ms)
2. Request workspace in closer region
3. Configure VPN split-tunnel for CDE traffic
4. Switch to wired connection if on WiFi

Prevention

Deploy CDEs in multiple regions, use edge networking, optimize SSH connection settings.

Symptoms

- "Connection reset by peer"
- IDE disconnects after idle time
- Terminal freezes then disconnects

Causes

- Firewall/NAT timeout killing idle connections
- Network instability
- Workspace auto-stop triggered

Solution

Add to ~/.ssh/config:

Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3
  TCPKeepAlive yes

Prevention

Configure SSH keepalive globally, extend auto-stop timeout, use tmux/screen for persistent sessions.

Performance Problems

Symptoms

- Characters appear after delay
- Autocomplete is slow
- File operations lag

Causes

- High CPU usage by language server
- Too many extensions enabled
- Large workspace with many files

Solution

1. Check CPU: top or htop
2. Disable unused VS Code extensions
3. Add large folders to .gitignore and exclude from search
4. Request workspace with more CPU cores

Symptoms

- Builds slower than local machine
- npm install takes forever
- Docker builds very slow

Causes

- No build cache configured
- Slow network storage
- Insufficient CPU/memory allocation

Solution

1. Enable persistent build cache (node_modules, .gradle, target/)
2. Use prebuilds for dependency installation
3. Mount fast local SSD for build directories
4. Configure Docker BuildKit with cache mounts

Symptoms

- "JavaScript heap out of memory"
- Process killed by OOM killer
- Workspace becomes unresponsive

Causes

- Workspace memory limit too low
- Memory leak in application
- Too many processes running

Solution

1. Check usage: free -h
2. For Node.js: export NODE_OPTIONS="--max-old-space-size=4096"
3. Request workspace template with more RAM
4. Kill unused background processes

IDE & Editor Issues

Solution

1. Update VS Code and Remote SSH extension to latest
2. Delete server: rm -rf ~/.vscode-server on remote
3. Check SSH config: coder config-ssh --yes
4. Try connecting via terminal first to verify SSH works

Solution

1. Ensure Coder plugin is installed in Gateway
2. Check Gateway version matches IDE backend version
3. Clear Gateway cache: Help > Delete Caches
4. Verify workspace has enough RAM (8GB+ recommended for JetBrains)

Solution

1. Some extensions run locally, others remotely - check extension docs
2. Reinstall extension on remote: Extensions > Install in SSH
3. Add required extensions to devcontainer.json for consistency
4. Check extension requires tools not in container (e.g., git, python)

Authentication Problems

Solution

1. Clear browser cookies for CDE domain
2. Try incognito/private browsing mode
3. Verify you're using correct identity provider
4. Contact admin if account not provisioned via SCIM

Solution

1. Re-authenticate: coder login https://cde.company.com
2. Generate new token in dashboard: Settings > Tokens
3. Update CLI: coder update
4. Check if your access was revoked by admin

Workspace Lifecycle

Solution

1. Check workspace logs in dashboard for errors
2. Verify resource quota not exceeded
3. Check if base image is accessible
4. Try recreating workspace from template
5. Contact platform team if infrastructure issue

Important

Only data in persistent volumes survives restarts. Ephemeral storage is lost.

Solution

1. Check what paths are persistent in your template
2. Common persistent: /home/coder, project directories
3. Always commit code to git regularly
4. Request template with more persistent storage

Solution

1. Check auto-stop setting in workspace config
2. Activity (SSH, web terminal) resets idle timer
3. Request longer TTL from platform team if needed
4. Use scheduled jobs to maintain activity for long builds

Database & Services

Solution

1. Check if database is in same VPC as workspace
2. Verify security group allows workspace IP range
3. Use internal DNS names, not public endpoints
4. Check credentials in secrets manager
5. Test with: nc -zv db-host 5432

Solution

1. Use Coder port forward: coder port-forward workspace 3000:3000
2. Or SSH: ssh -L 3000:localhost:3000 coder.workspace
3. Bind app to 0.0.0.0, not just localhost
4. Check if CDE has built-in port forwarding UI

Understanding

In remote development, "localhost" in your code means the workspace, not your laptop. But your browser runs on your laptop.

Solution

1. Use port forwarding to access workspace ports from browser
2. VS Code auto-forwards ports - check Ports panel
3. For API calls between services in workspace, localhost works
4. For browser access, use forwarded port or CDE preview URL

Resource Issues

Solution

1. Find large files: du -sh * | sort -h
2. Clean Docker: docker system prune -a
3. Clear package caches (npm, pip, gradle)
4. Remove old log files: find /var/log -type f -delete
5. Request workspace with larger disk

Solution

1. Verify workspace template includes GPU
2. Check GPU quota: you may need to request access
3. Run nvidia-smi to verify driver
4. Ensure NVIDIA container toolkit is installed
5. GPUs may be in short supply - try different region

Solution

1. Stop unused workspaces to free quota
2. Use smaller workspace templates when possible
3. Request quota increase from platform team
4. Check if org/team has shared quota limits

Still Stuck?

Check these additional resources or contact your platform team.

FAQ Glossary Contact Us