Troubleshooting - PinchTab

This guide covers common issues you might encounter when using PinchTab and how to resolve them.

Installation Issues

Command not found: pinchtab

Problem: Shell can’t find the pinchtab command after installation.Solution:Check if the binary is in your PATH:

which pinchtab

If not found, add the installation directory to your PATH:

echo 'export PATH="$HOME/.pinchtab/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Or use the full path:

~/.pinchtab/bin/pinchtab

Chrome not found

Problem: PinchTab can’t locate Chrome/Chromium.

ERROR: Chrome binary not found

Solution:Install Chrome or Chromium:

brew install --cask google-chrome

Or specify the Chrome binary path:

export CHROME_BIN=/path/to/chrome
pinchtab

Connection Issues

Connection refused (port 9867)

Problem: Can’t connect to PinchTab server.

curl http://localhost:9867/health
# curl: (7) Failed to connect to localhost port 9867: Connection refused

Solutions:

Check if PinchTab is running:
```
ps aux | grep pinchtab
```
Check if port is already in use:
```
lsof -i :9867
```
If another process is using it, either stop that process or change PinchTab’s port:
```
export BRIDGE_PORT=9999
pinchtab
```

Check firewall settings:

# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Linux (ufw)
sudo ufw status

CDP connection failed

Problem: Can’t connect to remote Chrome via CDP_URL.

ERROR: Failed to connect to CDP URL: connection refused

Solutions:

Verify Chrome is running with remote debugging:
```
curl http://localhost:9222/json/version
```
If this fails, start Chrome with debugging enabled:
```
google-chrome --remote-debugging-port=9222 &
```

Check the CDP_URL format:

# ✅ Correct
export CDP_URL="ws://localhost:9222/devtools/browser/abc123..."

# ❌ Wrong (http instead of ws)
export CDP_URL="http://localhost:9222/devtools/browser/abc123..."

Get the correct CDP_URL:

curl -s http://localhost:9222/json/version | jq -r '.webSocketDebuggerUrl'

Chrome Launch Issues

Chrome crashes on startup

Problem: Chrome crashes immediately after launch.Solutions:

Check Chrome version compatibility:
```
google-chrome --version
```
PinchTab requires Chrome 90+.

Try with additional flags (especially in Docker):

export CHROME_FLAGS="--no-sandbox --disable-dev-shm-usage --disable-gpu"
pinchtab

Clear profile directory:

rm -rf ~/.pinchtab/chrome-profile
pinchtab

Check available memory:
```
free -h
```
Chrome requires at least 512MB RAM. If low on memory, try headless mode:
```
export BRIDGE_HEADLESS=true
```

Invalid memory address error

Problem: Crash with “invalid memory address” error.

panic: runtime error: invalid memory address or nil pointer dereference

Solutions:

Ensure Chrome has at least one window/tab:

google-chrome --remote-debugging-port=9222 --new-window &

Clear state and restart:
```
rm -rf ~/.pinchtab/state
pinchtab
```
Use fresh start:
```
export BRIDGE_NO_RESTORE=true
pinchtab
```

Chrome zombie processes

Problem: Chrome processes remain after PinchTab exits.Solution:Kill orphaned Chrome processes:

# Kill all PinchTab-managed Chrome instances
pkill -f "Chrome.*user-data-dir.*\.pinchtab"

# Or more aggressively (kills ALL Chrome)
pkill chrome

To prevent this, always shut down PinchTab gracefully:

# Send SIGTERM (not SIGKILL)
kill <pinchtab-pid>

# Or use Ctrl+C in the terminal running PinchTab

Runtime Issues

Navigation timeout

Problem: Page navigation takes too long and times out.

ERROR: Navigation timeout after 60s

Solutions:

Increase navigation timeout:
```
export BRIDGE_NAV_TIMEOUT=120
```
Check network connectivity:
```
curl -I https://example.com
```

Block heavy resources to speed up loading:

export BRIDGE_BLOCK_IMAGES=true
export BRIDGE_BLOCK_MEDIA=true
export BRIDGE_NO_ANIMATIONS=true

Tab limit reached

Problem: Can’t create more tabs.

ERROR: Maximum tab limit reached (20)

Solutions:

Close unused tabs:

# List tabs
curl http://localhost:9867/tabs

# Close specific tab
curl -X DELETE http://localhost:9867/tabs/<tab-id>

Increase tab limit:
```
export BRIDGE_MAX_TABS=50
pinchtab
```

Too many tabs can cause high memory usage and slower performance.

High memory usage

Problem: PinchTab/Chrome consuming too much memory.Solutions:

Reduce max tabs:
```
export BRIDGE_MAX_TABS=5
```

Block heavy content:

export BRIDGE_BLOCK_IMAGES=true
export BRIDGE_BLOCK_MEDIA=true

Use headless mode:
```
export BRIDGE_HEADLESS=true
```

Close idle tabs programmatically:

# Get all tabs
TABS=$(curl -s http://localhost:9867/tabs | jq -r '.[].id')

# Close each tab
for tab in $TABS; do
  curl -X DELETE http://localhost:9867/tabs/$tab
done

Monitor memory usage:

# Linux
ps aux | grep -E '(pinchtab|chrome)' | awk '{sum+=$6} END {print sum/1024 " MB"}'

# macOS
ps aux | grep -E '(pinchtab|chrome)' | awk '{sum+=$6} END {print sum " MB"}'

Testing Issues

Tests failing with timeout

Problem: Integration tests timing out.Solution:Increase test timeout:

go test -tags integration ./tests/integration -timeout 300s

Or run tests with verbose output to see where it hangs:

go test -v -tags integration ./tests/integration -timeout 300s

Pre-commit hooks failing

Problem: Git commit blocked by pre-commit hooks.

gofmt............................................Failed

Solutions:

Install pre-commit:

pip install pre-commit
# or
brew install pre-commit

Setup hooks:
```
pre-commit install
```
Format code:
```
gofmt -w .
```
Run hooks manually:
```
pre-commit run --all-files
```
Update hooks:
```
pre-commit autoupdate
```

Docker/Container Issues

Chrome won't start in Docker

Problem: Chrome fails to start in containerized environment.Solution:Use required Chrome flags for containers:

ENV CHROME_FLAGS="--no-sandbox --disable-dev-shm-usage --disable-gpu"

Or in docker-compose:

environment:
  CHROME_FLAGS: "--no-sandbox --disable-dev-shm-usage --disable-gpu"
shm_size: 2gb

Explanation:

--no-sandbox: Required in most Docker setups (no kernel sandboxing)
--disable-dev-shm-usage: Fixes /dev/shm size issues
--disable-gpu: Containers often lack GPU access
shm_size: 2gb: Increases shared memory (fixes crashes)

Port conflicts in Docker

Problem: Port 9867 already in use on host.Solution:Map to a different host port:

docker run -p 8080:9867 pinchtab/pinchtab
# Access via http://localhost:8080

Or change PinchTab’s port:

docker run -e BRIDGE_PORT=8080 -p 8080:8080 pinchtab/pinchtab

Instance/Profile Issues

Instance won't start

Problem: Instance creation fails or hangs.Solution:

Check available ports:

# See what's using instance ports
lsof -i :9868-9968

Check instance limit:
```
curl http://localhost:9867/instances | jq length
```
Default limit is 100 instances (ports 9868-9968).

Manually stop stuck instances:

# List instances
curl http://localhost:9867/instances

# Stop specific instance
curl -X POST http://localhost:9867/instances/<instance-id>/stop

Clear state directory:
```
rm -rf ~/.pinchtab/state
pinchtab
```

Profile corruption

Problem: Chrome profile is corrupted, causing crashes or weird behavior.Solution:Delete and recreate profile:

rm -rf ~/.pinchtab/chrome-profile
pinchtab

This will clear all cookies, login sessions, and browser history.

For specific profiles:

rm -rf ~/.pinchtab/profiles/<profile-name>

Debugging

Enable Debug Logging

# Run with verbose output
pinchtab 2>&1 | tee pinchtab.log

# Filter for specific issues
pinchtab 2>&1 | grep -E "ERROR|WARN"

Check Health Endpoint

# Main server
curl http://localhost:9867/health

# Specific instance
curl http://localhost:9868/health

Inspect Running Instances

# List all instances
curl http://localhost:9867/instances | jq .

# Get instance details
curl http://localhost:9867/instances/<instance-id> | jq .

# List tabs in instance
curl http://localhost:9867/instances/<instance-id>/tabs | jq .

Monitor Chrome Processes

# See all PinchTab-related Chrome processes
ps aux | grep -E 'Chrome.*\.pinchtab'

# Watch memory usage in real-time
watch -n 1 'ps aux | grep -E "(pinchtab|chrome)" | awk '"'"'{sum+=$6} END {print sum/1024 " MB"}"'"''

Check Port Usage

# See which ports are in use
lsof -i :9867-9968

# Check specific port
lsof -i :9867

Test Script

Quick validation script:

test-pinchtab.sh

#!/bin/bash

set -e

echo "Testing PinchTab installation..."

# Check binary
if command -v pinchtab &> /dev/null; then
  echo "✅ pinchtab command found"
else
  echo "❌ pinchtab command not found"
  exit 1
fi

# Check Chrome
if command -v google-chrome &> /dev/null || command -v chromium &> /dev/null; then
  echo "✅ Chrome/Chromium found"
else
  echo "❌ Chrome/Chromium not found"
  exit 1
fi

# Start PinchTab in background
pinchtab &
PID=$!
sleep 3

# Test health endpoint
if curl -f http://localhost:9867/health &> /dev/null; then
  echo "✅ PinchTab server responding"
else
  echo "❌ PinchTab server not responding"
  kill $PID 2>/dev/null
  exit 1
fi

# Cleanup
kill $PID 2>/dev/null

echo "✅ All tests passed!"

Run it:

chmod +x test-pinchtab.sh
./test-pinchtab.sh

Getting Help

If you’re still stuck:

Check the logs:
```
pinchtab 2>&1 | tee debug.log
```
Search existing issues: https://github.com/pinchtab/pinchtab/issues
Open a new issue: Include:
- PinchTab version (pinchtab --version)
- Chrome version (google-chrome --version)
- Operating system
- Configuration (environment variables)
- Full error logs
- Steps to reproduce
Community support:
- GitHub Discussions
- Discord server (link in README)

Common Gotchas

Remember:

Always use export for environment variables
Environment variables override config file
Use BRIDGE_TOKEN when exposing to network
Chrome requires 512MB+ RAM
Docker requires --no-sandbox flag
CDP port has no auth (secure it!)
Headless mode uses less memory
Clean up orphaned Chrome processes

Documentation Index

​Installation Issues

​Connection Issues

​Chrome Launch Issues

​Runtime Issues

​Testing Issues

​Docker/Container Issues

​Instance/Profile Issues

​Debugging

​Enable Debug Logging

​Check Health Endpoint

​Inspect Running Instances

​Monitor Chrome Processes

​Check Port Usage

​Test Script

​Getting Help

​Common Gotchas

Installation Issues

Connection Issues

Chrome Launch Issues

Runtime Issues

Testing Issues

Docker/Container Issues

Instance/Profile Issues

Debugging

Enable Debug Logging

Check Health Endpoint

Inspect Running Instances

Monitor Chrome Processes

Check Port Usage

Test Script

Getting Help

Common Gotchas