CDE Troubleshooting Guide

Solution

1. 1. Verify API key is set: echo $OPENAI_API_KEY | head -c 8 (should show prefix)
2. 2. Test connectivity: curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" | head
3. 3. Check proxy settings: env | grep -i proxy
4. 4. For self-hosted LLMs, verify the inference server is running and reachable from the workspace subnet
5. 5. Ask your platform team to allowlist LLM API domains in workspace network policies

Solution

1. 1. Identify the process: top -o %MEM or top -o %CPU
2. 2. Set resource limits: ulimit -v 4194304 (4GB virtual memory cap)
3. 3. Kill runaway agents: pkill -f "agent-process-name"
4. 4. Clean agent caches: check ~/.cache/ and /tmp/ for large agent artifacts
5. 5. Request a workspace template with higher resource limits for AI workloads

Solution

1. 1. Check sandbox config for the agent tool you are using (Claude Code, Cursor, Copilot, etc.)
2. 2. Verify workspace user has write access: ls -la /workspace/
3. 3. For Coder or Ona (formerly Gitpod) workspaces, check template security policies
4. 4. Review Kubernetes securityContext if running in a pod-based CDE
5. 5. Ask platform team to adjust sandbox permissions for legitimate agent workflows

Solution

1. 1. Stop the agent immediately (Ctrl+C or kill the process)
2. 2. Review changes: git diff and git log --oneline -20
3. 3. Revert unwanted changes: git checkout -- . or git reset HEAD~N
4. 4. Re-run with more specific task instructions and smaller scope
5. 5. Enable agent confirmation mode (require approval before writes)

Solution

1. 1. Check current rate limit status in your LLM provider dashboard
2. 2. Switch to a higher-tier plan or request a rate limit increase
3. 3. Use per-developer API keys so one user does not exhaust the org quota
4. 4. Configure your agent/tool to use exponential backoff on 429 responses
5. 5. Reduce context window size to lower token consumption per request

Solution

1. 1. Test connectivity: curl -v http://llm-server:8000/health
2. 2. Verify DNS resolution: nslookup llm-server
3. 3. Check if inference server is running: kubectl get pods -l app=vllm
4. 4. Verify GPU health on the inference node: nvidia-smi
5. 5. Confirm workspace and inference server share network reachability (same VPC, peered VPC, or VPN)

Solution

1. 1. Measure raw latency: time curl -s $LLM_ENDPOINT/v1/models
2. 2. Reduce context size - exclude large files, vendor directories, and binaries
3. 3. Switch to a faster model for completions (use larger models only for complex tasks)
4. 4. For self-hosted LLMs, scale up replicas or use a model with lower VRAM requirements
5. 5. Check if your CDE provider offers edge-cached LLM endpoints

Solution

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

Solution

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

Solution

Add to ~/.ssh/config:

Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3
  TCPKeepAlive yes

Solution

1. 1. Check CPU: top or htop
2. 2. Disable unused VS Code extensions and AI tools you are not actively using
3. 3. Add large folders to .gitignore and exclude from search
4. 4. Request workspace with more CPU cores (4+ vCPUs for AI-heavy workflows)

Solution

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

Solution

1. 1. Check usage: free -h
2. 2. For Node.js: export NODE_OPTIONS="--max-old-space-size=4096"
3. 3. Request workspace template with more RAM (8GB+ for AI workflows)
4. 4. Kill unused background processes and idle AI agent sessions

Solution

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

Solution

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

Solution

1. 1. Some extensions run locally, others remotely - check extension docs
2. 2. Reinstall extension on remote: Extensions > Install in SSH
3. 3. Add required extensions to devcontainer.json for consistency
4. 4. Check extension requires tools not in container (e.g., git, python, node)
5. 5. For AI coding extensions (Copilot, Codeium, Continue), verify API key injection and network access from the workspace

Solution

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

Solution

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

Solution

1. 1. Check if the key is injected as an environment variable: env | grep -i api_key
2. 2. Verify your workspace template includes the secret from your CDE secrets manager
3. 3. For Coder: check workspace parameters and secrets in your template
4. 4. For Ona: verify environment variables in your workspace configuration
5. 5. Rotate the key if it may have been exposed or expired

Solution

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

Solution

1. 1. Check what paths are persistent in your template
2. 2. Common persistent: /home/coder, project directories
3. 3. Always commit code to git regularly
4. 4. Request template with more persistent storage
5. 5. AI agent conversation history may be lost - export or sync agent state to a persistent path

Solution

1. 1. Check auto-stop setting in workspace config
2. 2. Activity (SSH, web terminal) resets idle timer
3. 3. Request longer TTL from platform team if needed
4. 4. Use scheduled jobs to maintain activity for long-running builds or agent tasks
5. 5. For autonomous AI agents running overnight, ensure the workspace TTL exceeds the expected task duration

Solution

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

Solution

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

Solution

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

Solution

1. 1. Find large files: du -sh * | sort -h
2. 2. Clean Docker: docker system prune -a
3. 3. Clear package caches (npm, pip, gradle)
4. 4. Remove old log files and AI agent caches in ~/.cache/
5. 5. Request workspace with larger disk

Solution

1. 1. Verify workspace template includes GPU
2. 2. Check GPU quota: you may need to request access
3. 3. Run nvidia-smi to verify driver
4. 4. Ensure NVIDIA container toolkit is installed
5. 5. GPUs may be in short supply - try different region or off-peak hours
6. 6. For local LLM inference, verify the model fits in available VRAM

Solution

1. 1. Stop unused workspaces to free quota
2. 2. Use smaller workspace templates when possible
3. 3. Request quota increase from platform team
4. 4. Check if org/team has shared quota limits
5. 5. Review if autonomous AI agents are consuming quota by leaving workspaces running after task completion