Troubleshooting¶

Common issues and solutions for acp-amp.

Installation Issues¶

"pip: command not found"¶

Install Python first:

# macOS
brew install python

# Ubuntu/Debian
sudo apt install python3 python3-pip

# Or use uv
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install acp-amp

"npm: command not found"¶

Install Node.js first:

# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

"acp-amp: command not found" (after pip install)¶

The install location might not be in your PATH:

# Find where it was installed
python -m site --user-base
# Usually: ~/.local/bin/acp-amp

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Or use the full path
~/.local/bin/acp-amp run

"Permission denied" during install¶

Don't use sudo with pip. Instead:

# Use --user flag
pip install --user acp-amp

# Or use pipx/uv
pipx install acp-amp
uv tool install acp-amp

Amp CLI Issues¶

"amp: command not found"¶

Install the Amp CLI:

curl -fsSL https://ampcode.com/install.sh | bash

If still not found, check npm global bin path:

npm bin -g
# Add this to your PATH

"Not authenticated" or "API key required"¶

Login to Amp:

amp login

Or provide an API key:

export AMP_API_KEY="your-api-key"
acp-amp run

"Invalid API key"¶

Check your API key is correct
Try logging in again: amp login
Get a new key from Amp settings

Python SDK Issues¶

"'SystemMessage' object has no attribute 'get'"¶

This was a bug in older versions. Update to latest:

pip install --upgrade acp-amp

If it persists, use the Node shim fallback:

acp-amp run --driver node

"amp-sdk is not installed"¶

The Python SDK should install automatically. If not:

pip install amp-sdk

"No module named 'acp_amp'"¶

Reinstall the package:

pip uninstall acp-amp
pip install acp-amp

Python version too old¶

acp-amp requires Python 3.10+:

python --version
# If < 3.10, upgrade Python

Node Shim Issues¶

"Cannot find module" errors¶

Install the shim dependencies:

acp-amp setup
cd ~/.acp-amp/shim
npm install

"Node.js version too old"¶

acp-amp requires Node.js 18+:

node --version
# If < 18, upgrade Node.js

Shim not found¶

Specify the shim path:

ACP_AMP_SHIM=/path/to/shim/index.js acp-amp run --driver node

Zed Issues¶

Check your settings.json syntax
Make sure there are no trailing commas
Restart Zed completely (Cmd+Q / Ctrl+Q)

"Failed to start agent"¶

Test the command manually:

acp-amp run
# or
npx @superagenticai/acp-amp

Check Zed's output panel for errors
Use full path in settings

Agent starts but no response¶

Make sure you're logged into Amp: amp login
Check if API key is set correctly in env
Check Zed's output panel for errors

npx is slow on first run¶

First run downloads the package. For faster startup:

# Install globally instead
npm install -g @superagenticai/acp-amp

Then update Zed settings to use acp-amp instead of npx.

Connection Issues¶

"Connection refused" or timeout¶

Check internet connection
Try amp login to verify authentication
Check if Amp service is up

"Stream closed unexpectedly"¶

Update to latest version
Check stderr output for errors
Try the other version (Python ↔ Node.js)

Debugging¶

Enable verbose output¶

# See what's happening
acp-amp run 2>&1 | tee debug.log

Check stderr¶

Logs go to stderr, not stdout:

acp-amp run 2>error.log
cat error.log

Test JSON-RPC manually¶

# Start acp-amp
acp-amp run

# In another terminal, send test message
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | nc localhost 3000

Zed logs¶

Check Zed's logs:

# macOS
tail -f ~/Library/Logs/Zed/Zed.log

# Linux
tail -f ~/.local/share/zed/logs/Zed.log

Getting Help¶

If none of these solutions work:

Check GitHub Issues: github.com/SuperagenticAI/acp-amp/issues
Open a new issue with:
Your OS and version
Python/Node.js version
acp-amp version (pip show acp-amp or npm list -g @superagenticai/acp-amp)
Full error message
Steps to reproduce
Community support:
Amp Discord
Zed Discord

Version Information¶

Get version info for bug reports:

# Python version
pip show acp-amp
python --version

# Node.js version
npm list -g @superagenticai/acp-amp
node --version

# Amp CLI version
amp --version