Common Issues

Quick solutions for frequently encountered problems.

App Won't Launch

Symptom: The app opens briefly then closes, or shows a blank window.

Solutions:

1. macOS Gatekeeper: Right-click the app → Open (bypasses first-launch block)
2. Corrupted state: Delete ~/.config/crab-desktop/ and relaunch
3. GPU issues: Launch with --disable-gpu flag to skip WebGL rendering
4. Port conflict: Another Electron app may hold a debug port. Close other Electron apps and retry.

Blank White Screen

Symptom: The window opens but shows nothing.

Solutions:

1. Press Cmd+Shift+I to open DevTools — check the Console for errors
2. If you see "Failed to fetch dynamically imported module", the app auto-reloads once. If it persists, clear cache: Settings → Reset → Clear State & Reload
3. Try Cmd+R to reload the window

Operations Hang or Time Out

Symptom: Clone, push, or hydrate operations never complete.

Solutions:

1. Check network connectivity
2. Verify cloud credentials haven't expired (Settings → Storage)
3. Check the Health view for agent status — if the agent crashed, it auto-restarts within 30 seconds
4. Cancel the operation (click the × in the Progress Drawer) and retry

"Stale Hunk" Error When Staging

Symptom: Staging a hunk fails with "stale hunk anchor" error.

Cause: The file was modified after the diff was loaded (by another tool, auto-formatter, or file watcher).

Solution: Click Refresh in the Changes view toolbar to reload the diff, then stage again.

Commit Button Disabled

Symptom: The Commit button is greyed out.

Check the readiness indicator:

• No staged changes → stage files first
• Empty commit message → enter a message
• Merge conflict unresolved → resolve in the Conflicts view

File Tree Not Updating

Symptom: Files created or deleted externally don't appear.

Solutions:

1. Click Refresh in the Explorer toolbar
2. Check that the file isn't in an ignored directory (.gitignore, node_modules/)
3. Verify the file watcher is enabled: Settings → Workspace → File Watcher

Forge Features Missing (No PR View)

Symptom: The Pull Requests view doesn't appear in the activity bar.

Cause: No forge provider detected for the repository.

Solutions:

1. Ensure the repo has a remote URL pointing to GitHub, GitLab, or Bitbucket
2. Configure authentication: Settings → Integrations
3. Check that the remote is reachable: git ls-remote origin

Terminal Shows Wrong Shell or Missing Tools

Symptom: Terminal doesn't have your usual PATH, or tools like node, python aren't found.

Cause: GUI apps on macOS don't inherit your shell's PATH.

Solutions:

1. The app resolves your login shell PATH on startup. If you recently installed tools, restart the app.
2. Check that your tools are in standard locations (~/.cargo/bin, /opt/homebrew/bin, ~/.local/bin)
3. For nvm/mise users: the app detects these automatically, but a restart may be needed after first install.

Auto-Update Fails

Symptom: Update banner appears but download fails or app doesn't restart.

Solutions:

1. Download the latest version manually from crab.build/desktop
2. On macOS: ensure the app is in /Applications (not running from DMG)
3. On Linux AppImage: ensure the file is writable (auto-update replaces the file in place)