Common Issues

Running into a problem? This guide covers the most common issues ShellPod users encounter and how to fix them.

Terminal will not connect

Symptom: You click "Open Terminal" but get a blank screen, loading spinner that never resolves, or a connection error.

Solutions:

1. Check your session status: Go to your dashboard and verify your session shows "Running." If it shows "Stopped," click "Start Session" first.
2. Hard refresh: Press Ctrl+Shift+R (or Cmd+Shift+R on Mac) to do a hard refresh. Sometimes the browser caches a stale session token.
3. Try a different browser: If the terminal works in Chrome but not Safari (or vice versa), it may be a browser-specific WebSocket issue. Chrome and Firefox generally have the best compatibility.
4. Check your network: The terminal uses WebSockets, which some corporate firewalls or VPNs block. Try disconnecting from your VPN or switching to a different network.
5. Wait and retry: If you just started your session, give it 15-20 seconds for the container to fully boot before opening the terminal.

Claude Code will not start

Symptom: You type claude in the terminal but get an error or nothing happens.

Solutions:

1. Check authentication: If you see an authentication error, your Anthropic credentials may have expired. Run claude and go through the auth flow again.
2. Check your API key: If using an API key, verify it is still valid at console.anthropic.com. Keys can be revoked or expire.
3. Check your subscription: If using Pro/Max authentication, make sure your Anthropic subscription is active.
4. Try updating: Run claude update or npm update -g @anthropic-ai/claude-code to get the latest version.
5. Check disk space: Run df -h to check if your disk is full. Claude Code needs space for its cache and temporary files.

Disk full

Symptom: Commands fail with "No space left on device" or packages fail to install.

Solutions:

1. Check usage: Run df -h to see disk usage and du -sh ~/* | sort -rh | head -20 to find the biggest directories.
2. Clean npm cache: npm cache clean --force can free up significant space.
3. Remove node_modules: If you have cloned multiple projects, remove node_modules from projects you are not actively working on: rm -rf ~/old-project/node_modules
4. Clean git: Run git gc --aggressive in your repos to compress git objects.
5. Check for large files: find ~ -type f -size +100M to find files over 100MB that you might not need.

Slow performance

Symptom: Commands feel sluggish, Claude Code responses are slow, or the terminal lags.

Solutions:

1. Check running processes: Run top or htop to see if something is consuming all the CPU or memory. Kill any runaway processes.
2. Network latency: If the terminal itself feels laggy (keystrokes take a moment to appear), the issue is network latency between your device and the server. Try a wired connection instead of WiFi.
3. Too many tmux panes: Each tmux pane with active output consumes resources. Close panes you are not using.
4. Large repositories: If Claude Code is slow to start, it might be scanning a very large repository. Add a .claudeignore file to exclude directories like node_modules, .git, or large asset directories.
5. Restart your session: If performance has degraded over time, stop and start your session from the dashboard. This gives you a fresh container process while keeping all your files.

Git push/pull fails

Symptom: git push or git pull gives a permission denied error.

Solutions:

1. Check SSH key: Run ssh -T git@github.com to test your SSH connection. If it fails, your SSH key may not be added to GitHub. See our Connecting Your Repo guide.
2. Check remote URL: Run git remote -v to verify you are using the SSH URL (starts with git@github.com:) not HTTPS.
3. SSH agent: If you set a passphrase on your SSH key, you need to add it to the SSH agent: eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519

Session shows "Error" status

Symptom: Your dashboard shows your session in an "Error" state.

Solutions:

1. Stop and restart: Click "Stop Session" then "Start Session" from the dashboard. This provisions a fresh container process while keeping your persistent storage.
2. Wait a moment: Occasionally, the status display can lag behind the actual state. Refresh your dashboard page.
3. Contact support: If the error persists after stopping and starting, reach out on the ShellPod Discord with your account details.

Still stuck?

If none of the above solutions work for your issue:

• Join the ShellPod Discord and describe your issue — the community and team are there to help
• Check the FAQ for answers to common questions
• Try creating a snapshot and then resetting your container as a last resort