Skip to content

troubleshooting.md

Latest commit

 

History

History
193 lines (125 loc) · 6.95 KB

troubleshooting.md

File metadata and controls

193 lines (125 loc) · 6.95 KB
Raw

Troubleshooting Guide

Quick Diagnostics

cc-clip doctor --host myserver

Step-by-Step Verification

If image paste isn't working, run these checks in order to isolate the problem:

# 1. Local: Is the daemon running?
curl -s http://127.0.0.1:18339/health
# Expected: {"status":"ok"}

# 2. Remote: Is the tunnel forwarding?
ssh myserver "curl -s http://127.0.0.1:18339/health"
# Expected: {"status":"ok"}

# 3. Remote: Is the shim taking priority over real xclip?
ssh myserver "which xclip"
# Expected: /home/<user>/.local/bin/xclip  (NOT /usr/bin/xclip)

# 4. Remote: Does the shim intercept correctly? (copy an image on Mac first)
ssh myserver 'CC_CLIP_DEBUG=1 xclip -selection clipboard -t TARGETS -o'
# Expected: image/png

SSH ControlMaster Breaks RemoteForward

Symptom: cc-clip connect reports "tunnel verified", but the tunnel doesn't work in your interactive SSH session. curl -s http://127.0.0.1:18339/health hangs on the remote.

Cause: If you use SSH ControlMaster auto (connection multiplexing), the first SSH connection becomes the "master". All subsequent connections reuse the master — even if you later add RemoteForward to your config. The old master connection does not have the port forwarding, so the tunnel silently fails.

Fix: cc-clip setup automatically adds ControlMaster no for your host. If you configured SSH manually:

# ~/.ssh/config
Host myserver
    HostName 10.x.x.x
    User myuser
    RemoteForward 18339 127.0.0.1:18339
    ControlMaster no
    ControlPath none

This ensures every SSH connection creates a fresh tunnel. The trade-off is slightly slower connection setup (no multiplexing), but it guarantees RemoteForward works reliably.

Stale sshd Process Blocks RemoteForward

Symptom: ssh myserver shows Warning: remote port forwarding failed for listen port 18339. The tunnel never works regardless of how many times you reconnect.

Cause: A previous SSH session left a stale sshd child process on the remote server that is still holding port 18339. New SSH connections cannot bind RemoteForward to a port that's already in use.

Diagnosis (on remote):

sudo ss -tlnp | grep 18339
# Shows: sshd,pid=XXXXX listening on 18339

Fix:

# On remote: kill the stale sshd process
sudo kill <PID>

# Then reconnect from local
ssh myserver
curl -s http://127.0.0.1:18339/health
# Expected: {"status":"ok"}

Prevention: Update to the latest cc-clip. The connect command uses ClearAllForwardings=yes for its internal SSH session, so it never competes for the RemoteForward port.

Token Expired or Invalid

Symptom: "fetch type failed" or "token invalid" / "401" in shim debug logs. Image paste silently falls back to the remote (empty) clipboard.

Cause: Token TTL (30 days) expired due to prolonged inactivity, or daemon restarted and generated a new token.

Fix:

# Re-sync token without re-uploading the binary
cc-clip connect myserver --token-only

The token uses sliding expiration — it auto-renews on every successful request. You'll only hit this after 30+ days of zero usage.

To force a new token: cc-clip serve --rotate-token.

Launchd Daemon Returns "empty" for Image Clipboard

Symptom: cc-clip service install is running, but /clipboard/type returns {"type":"empty"} even when you have an image in your Mac clipboard. Running cc-clip serve in the foreground works correctly.

Cause: macOS launchd does not source your shell profile, so PATH doesn't include Homebrew directories (/opt/homebrew/bin on Apple Silicon, /usr/local/bin on Intel). The daemon can't find pngpaste.

Fix: Reinstall the service to regenerate the plist with correct PATH:

cc-clip service uninstall
cc-clip service install

Empty Image Data (API Error 400)

Symptom: Claude Code returns API Error: 400 — image cannot be empty. The conversation becomes corrupted and all subsequent image pastes fail in the same session.

Cause: A race condition where the clipboard content changes between the TARGETS check and the image fetch. The shim outputs empty data, and Claude Code sends an empty base64 image to the API.

Fix:

  1. In Claude Code, run /clear or start a new session (the old conversation is corrupted)
  2. Update to the latest cc-clip and re-run cc-clip connect myserver

~/.local/bin Not in PATH

Symptom: cc-clip connect shows WARNING: 'which xclip' resolves to /usr/bin/xclip, not ~/.local/bin/xclip.

Cause: The shim is installed to ~/.local/bin/ but it's not first in PATH, so the system uses /usr/bin/xclip instead.

Fix: cc-clip connect auto-detects your remote shell and prepends a PATH marker to the appropriate rc file. If auto-fix didn't work, add manually:

# Add to the TOP of ~/.bashrc (before the interactive guard)
export PATH="$HOME/.local/bin:$PATH"

Verify with which xclip — it should point to ~/.local/bin/xclip.

No Image in Clipboard

Symptom: Shim returns image/png for TARGETS but Claude Code says "No image found in clipboard".

Cause: You may not have an image in your Mac clipboard.

Fix: Copy an image on your Mac first:

  • Screenshot to clipboard: Cmd + Shift + Ctrl + 4 (select area) or Cmd + Shift + Ctrl + 3 (full screen)
  • Copy from an app: Right-click an image → Copy Image

Clipboard-History Manager "Paste" Button Bypasses cc-clip

Symptom: You copied an image, but pasting it into remote Claude Code / Codex via a clipboard-history manager's "Paste to " button inserts the image's file path as text instead of the image. cc-clip never seems to fire.

Cause: This is a usage gotcha, not a cc-clip failure. Clipboard-history managers (Raycast, Maccy, Paste) "Paste to " buttons inject the file path as text — they do not trigger the agent's own clipboard read. cc-clip only serves the clipboard when the agent itself reads it, via the xclip shim (Claude Code) or arboard (Codex). A manager that types a path on your behalf goes around that read entirely.

Fix: Paste with the agent's own Ctrl+V, after copying the image as raw image data (not a file reference):

  • Take a fresh screenshot to the clipboard (Cmd + Shift + Ctrl + 4 / Cmd + Shift + Ctrl + 3), or right-click an image → Copy Image.
  • In the remote Claude Code / Codex session, press Ctrl+V directly.

Do not use the clipboard manager's paste button for images — it never hands the raw image to the agent, so cc-clip is never asked for it.

Setup Fails: "killed" During Re-Deployment

Symptom: cc-clip setup was working before, but now shows zsh: killed when re-running.

Cause: The launchd service is running the old binary. Replacing the binary while the daemon holds it open can cause conflicts.

Fix:

cc-clip service uninstall
curl -fsSL https://raw.githubusercontent.com/ShunmeiCho/cc-clip/main/scripts/install.sh | sh
cc-clip setup myserver