Skip to main content

Installation Problems

Installation Problems

Common installation issues and solutions for the LLM platform components.

BuildKit Installation Issues

NPM Registry Authentication

Problem: Cannot install from GitLab npm registry.

npm ERR! 401 Unauthorized

Solution:

# Create/update ~/.npmrc
echo "@bluefly:registry=https://gitlab.com/api/v4/packages/npm/" >> ~/.npmrc
echo "//gitlab.com/api/v4/packages/npm/:_authToken=YOUR_TOKEN" >> ~/.npmrc

# Get token from
open https://gitlab.com/-/user_settings/personal_access_tokens

Permission Denied

Problem: Global install fails with EACCES.

npm ERR! Error: EACCES: permission denied

Solution:

# Option 1: Use npx (recommended)
npx @bluefly/agent-buildkit --help

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Docker Issues

Docker Not Running

Problem: Cannot connect to Docker daemon.

Error: Cannot connect to the Docker daemon

Solution:

# macOS - Start Docker Desktop
open -a Docker

# Linux - Start Docker service
sudo systemctl start docker

# Verify
docker ps

Port Already in Use

Problem: Port conflict when starting services.

Error: bind: address already in use

Solution:

# Find process using port
lsof -i :6006

# Kill process
kill -9 <PID>

# Or use different port
docker run -p 6007:6006 arizephoenix/phoenix

Database Issues

PostgreSQL Connection Failed

Problem: Cannot connect to PostgreSQL.

Error: connection refused

Solution:

# Check PostgreSQL is running
docker ps | grep postgres

# Start PostgreSQL
docker-compose up -d postgres

# Verify connection
psql -h localhost -U postgres -d llm_platform

Neo4j Authentication

Problem: Neo4j authentication failed.

Solution:

# Reset Neo4j password
docker run -e NEO4J_AUTH=neo4j/newpassword neo4j:latest

# Update environment variables
export NEO4J_PASSWORD=newpassword

Kubernetes Issues

kubectl Not Found

Problem: kubectl command not available.

Solution:

# macOS
brew install kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

Context Not Set

Problem: No cluster context configured.

Solution:

# List contexts
kubectl config get-contexts

# Set context (OrbStack)
kubectl config use-context orbstack

# Verify
kubectl cluster-info

Node.js Issues

Wrong Node Version

Problem: Requires Node.js >= 18.

Solution:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node 20
nvm install 20
nvm use 20

# Verify
node --version  # Should be v20.x.x

Python Issues

Missing Dependencies

Problem: ModuleNotFoundError

Solution:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

GitLab Issues

Cannot Clone Repository

Problem: Permission denied (publickey).

Solution:

# Generate SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"

# Add to GitLab
cat ~/.ssh/id_ed25519.pub
# Paste at: https://gitlab.com/-/profile/keys

# Test connection
ssh -T git@gitlab.com

Related Pages