Install Troubleshooting

This page covers common issues when installing Crawdad via curl https://getcrawdad.dev/install.sh | sh. If your issue isn't listed here, contact contact@getcrawdad.dev with the exit code and error message from the installer.

"Crawdad health endpoint did not respond within 10 seconds"

The sidecar binary installed successfully but didn't start listening on port 7749 within the install script's 10-second window. Most common causes:

Port 7749 already in use by another process

Check what's binding it:

# Linux
sudo ss -tlnp | grep 7749

# macOS
sudo lsof -i :7749

Stop the conflicting process, or change Crawdad's port (set CRAWDAD_PORT=7799 in the systemd unit's Environment= line on Linux, or in the launchd plist's EnvironmentVariables block on macOS).

Sidecar crashed on startup

View the logs:

# Linux (systemd journal)
sudo journalctl -u crawdad-sidecar --no-pager -n 100

# macOS (launchd logs)
cat /tmp/crawdad.err
cat /tmp/crawdad.log

Common errors in the logs:

Permission denied on ~/.local/share/crawdad/ — directory permissions broken; remove (sudo rm -rf ~/.local/share/crawdad) and re-run install.sh
Failed to bind 127.0.0.1:7749 — port already in use (see above)
ML library load failure — usually transient on first run; the deferred ML download takes ~2 minutes after first start

The sidecar started slowly

Some systems take longer than 10 seconds to fully initialize. Wait 30 seconds, then retry:

curl -s http://127.0.0.1:7749/v1/health

If you get JSON back, Crawdad is healthy.

"Binary failed to execute on this platform"

The installer ran the binary's --version smoke test and it failed. Three causes:

Wrong architecture

Confirm your platform:

# Linux and macOS
uname -m

Crawdad supports arm64 (Apple Silicon, AWS Graviton, Raspberry Pi 4+) and x86_64. Other architectures aren't currently supported — email contact@getcrawdad.dev with details.

glibc too old (Linux only)

Linux binaries require glibc 2.28+. Check:

# Linux only
ldd --version | head -1

glibc 2.28+ covers Debian 10+, Ubuntu 18.04+, RHEL 8+, Amazon Linux 2023.

Binary signature or arch mismatch (macOS)

Check:

# macOS only
file /usr/local/bin/crawdad-sidecar
codesign -dv /usr/local/bin/crawdad-sidecar 2>&1 | head -3

If file returns “Mach-O 64-bit executable arm64” and codesign shows the binary signed and notarized, the binary is fine — the issue is environmental.

"systemd not available on this distribution"

Crawdad's auto-start service requires systemd. Distros without systemd (Alpine, OpenWrt, distroless containers, custom embedded Linux) install the binary correctly but skip service registration.

The binary works — start it manually:

/usr/local/bin/crawdad-sidecar run &

For production deployments on non-systemd init systems (OpenRC, runit, supervisord, s6), email contact@getcrawdad.dev.

"Could not resolve home directory for user"

install.sh tried to determine the service user's home directory and failed. Usually happens in custom Docker images, distroless containers, or embedded systems where /etc/passwd is stripped.

Workaround: explicitly set USER:

USER=root curl -fsSL https://getcrawdad.dev/install.sh | sudo sh

On a normal Linux distribution, this error is a bug — email contact@getcrawdad.dev with getent passwd $USER output and your distro/version.

"Crawdad is already running" or port conflict on reinstall

If you see “Port 7744 is already in use” when running install.sh again, an older Crawdad is still active.

# macOS
launchctl unload ~/Library/LaunchAgents/com.crawdad.sidecar.plist
sudo pkill -f crawdad-sidecar

# Linux
sudo systemctl stop crawdad-sidecar

Then re-run install.sh.

"Download failed"

install.sh couldn't download the binary from R2.

Corporate firewall

Ask IT to allowlist *.getcrawdad.dev and crawdad-releases.r2.cloudflarestorage.com.

Network test

curl -fsSL -o /tmp/crawdad-test https://getcrawdad.dev/download/v0.12.1/crawdad-linux-x86_64
ls -lh /tmp/crawdad-test

Should be ~29MB. If it fails, the issue is your network reaching Cloudflare. Try a different network.

Transient CDN issue

Wait 5 minutes and re-run install.sh.

"Unsupported platform"

Crawdad currently supports:

macOS Apple Silicon (arm64) — full ML detection, signed + notarized
macOS Intel (x86_64) — pattern-based detection only (upstream ONNX Runtime has no 1.24+ wheel for this target)
Linux x86_64 (glibc 2.28+) — full ML detection
Linux ARM64 (aarch64, glibc 2.28+) — full ML detection

Other OS or architecture: email contact@getcrawdad.dev.

How to fully uninstall Crawdad

macOS

curl -fsSL https://getcrawdad.dev/uninstall.sh | sh

Or manually:

launchctl unload ~/Library/LaunchAgents/com.crawdad.sidecar.plist
rm ~/Library/LaunchAgents/com.crawdad.sidecar.plist
sudo rm /usr/local/bin/crawdad-sidecar
rm -rf ~/.local/share/crawdad
rm -rf "~/Library/Application Support/crawdad"
# Remove the ANTHROPIC_BASE_URL line from your shell profile (~/.zshrc or ~/.bashrc)

Linux

curl -fsSL https://getcrawdad.dev/uninstall.sh | sudo sh

Or manually:

sudo systemctl stop crawdad-sidecar
sudo systemctl disable crawdad-sidecar
sudo rm /etc/systemd/system/crawdad-sidecar.service
sudo systemctl daemon-reload
sudo rm /usr/local/bin/crawdad-sidecar
rm -rf ~/.local/share/crawdad
sudo rm -rf /var/log/crawdad
# Remove the ANTHROPIC_BASE_URL line from your shell profile (~/.bashrc or ~/.zshrc)

Still stuck?

Email contact@getcrawdad.dev with:

Your OS and version (uname -a)
install.sh's full output
Output of curl -s http://127.0.0.1:7749/v1/health (or "no response")
Logs:
- macOS: /tmp/crawdad.log and /tmp/crawdad.err
- Linux: sudo journalctl -u crawdad-sidecar --no-pager -n 100

We respond within 24 hours.