Skip to main content

Troubleshooting the PipeOps CLI

Common issues and solutions when using the PipeOps CLI.

Installation Issues​

Command Not Found​

Problem: After installation, pipeops command is not found.

Solution:

  1. Check if the binary is in your PATH:

    echo $PATH

  2. Add the installation directory to PATH:

    # For bash
    echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
    source ~/.bashrc

    # For zsh
    echo 'export PATH=$PATH:/usr/local/bin' >> ~/.zshrc
    source ~/.zshrc

  3. Verify the binary location:

    which pipeops
    ls -l /usr/local/bin/pipeops

Permission Denied​

Problem: Cannot execute the CLI binary.

Solution:

# Make the binary executable
sudo chmod +x /usr/local/bin/pipeops

# Or reinstall with proper permissions
sudo curl -fsSL https://get.pipeops.dev/cli.sh | bash

Wrong Architecture​

Problem: "cannot execute binary file: Exec format error"

Solution:

  1. Check your system architecture:

    uname -m

  2. Download the correct binary:

    • x86_64 or amd64: Intel/AMD processors
    • arm64 or aarch64: ARM processors (e.g., Apple Silicon)

Authentication Issues​

Authentication Failed​

Problem: pipeops auth login fails.

Solutions:

  1. Check network connectivity:

    curl -v https://api.pipeops.io/health

  2. Clear existing configuration:

    rm ~/.pipeops.json
    pipeops auth login

  3. Use manual browser authentication:

    pipeops auth login --no-browser
    # Copy and paste the URL into your browser

Token Expired​

Problem: "authentication token has expired"

Solution:

# Re-authenticate
pipeops auth logout
pipeops auth login

Invalid Token​

Problem: Commands fail with "invalid token" error.

Solution:

  1. Check token in configuration:

    cat ~/.pipeops.json

  2. Verify token format:

    # Token should be a JWT (starts with eyJ)
    echo $PIPEOPS_AUTH_TOKEN

  3. Re-authenticate:

    pipeops auth login

Command Execution Issues​

Command Timeout​

Problem: Commands hang or timeout.

Solutions:

  1. Check API connectivity:

    curl -v https://api.pipeops.io/health

  2. Retry the request:

    pipeops list --json

  3. Check for proxy issues:

    # Verify proxy settings
    echo $HTTP_PROXY
    echo $HTTPS_PROXY

    # Temporarily disable proxy
    unset HTTP_PROXY HTTPS_PROXY
    pipeops list

Rate Limiting​

Problem: "Too many requests" or 429 error.

Solution:

  1. Wait and retry:

    sleep 60
    pipeops list

  2. Implement retry logic in scripts:

    for i in {1..3}; do
      if pipeops status proj-123; then
        break
      fi
      sleep 30
    done

API Errors​

Problem: 500, 502, 503 errors from API.

Solution:

  1. Check PipeOps status page
  2. Retry after a few moments
  3. Use verbose mode to see details: 
    pipeops project list --verbose

Project and Deployment Issues​

Project Not Found​

Problem: "project not found" error.

Solutions:

  1. List available projects:

    pipeops list

  2. Check project ID:

    # Get the correct project ID
    pipeops list --json | jq '.[] | {id, name}'

  3. Set default project:

    export PIPEOPS_DEFAULT_PROJECT=proj-123

Deployment Failures​

Problem: Project issues.

Solutions:

  1. Check project logs:

    pipeops logs proj-123

  2. Verify project status:

    pipeops status proj-123

  3. List project information:

    pipeops list --json | jq '.[] | select(.id=="proj-123")'

  4. Use the web UI for detailed diagnostics and management

Configuration Issues​

Config File Errors​

Problem: "invalid config file" or JSON parse errors.

Solution:

  1. Validate JSON:

    cat ~/.pipeops.json | jq .

  2. Reset configuration:

    mv ~/.pipeops.json ~/.pipeops.json.backup
    echo '{}' > ~/.pipeops.json
    pipeops auth login

Environment Variables Not Working​

Problem: Environment variables are ignored.

Solutions:

  1. Verify variable is exported:

    export PIPEOPS_API_URL=https://api.pipeops.io
    echo $PIPEOPS_API_URL

  2. Check variable precedence:

    • Command flags override environment variables
    • Environment variables override config file

  3. Use correct variable names:

    # Correct
    export PIPEOPS_AUTH_TOKEN="..."

    # Incorrect
    export PIPEOPS_TOKEN="..."  # Wrong name

Network Issues​

Proxy Problems​

Problem: Cannot connect through corporate proxy.

Solution:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

# With authentication
export HTTP_PROXY=http://user:pass@proxy.company.com:8080

SSL Certificate Errors​

Problem: SSL verification failures.

Solutions:

  1. Update CA certificates:

    # Ubuntu/Debian
    sudo apt-get update
    sudo apt-get install ca-certificates

    # macOS
    brew install ca-certificates

  2. Verify PipeOps certificate:

    openssl s_client -connect api.pipeops.io:443

DNS Resolution Issues​

Problem: Cannot resolve api.pipeops.io.

Solution:

# Test DNS resolution
nslookup api.pipeops.io
dig api.pipeops.io

# Try alternate DNS
# Google DNS
export PIPEOPS_API_URL=https://8.8.8.8  # Not recommended

Agent Installation Issues​

Agent Install Fails​

Problem: pipeops agent install fails.

Solutions:

  1. Check prerequisites:

    # Verify system requirements
    free -h  # Check memory (min 2GB)
    df -h    # Check disk space (min 20GB)

  2. Run with sudo:

    sudo pipeops agent install

  3. Check port availability:

    # Verify ports are not in use
    sudo lsof -i :6443
    sudo lsof -i :10250

  4. View installation logs:

    sudo pipeops agent install --verbose

Agent Join Fails​

Problem: Cannot join worker node to cluster.

Solutions:

  1. Verify join token:

    # Get new token from control plane
    sudo pipeops agent info --show-join-token

  2. Check network connectivity:

    # Test connection to control plane
    telnet <control-plane-ip> 6443

  3. Check firewall rules:

    # Ensure required ports are open
    sudo ufw status

Performance Issues​

Slow Command Execution​

Problem: Commands are very slow.

Solutions:

  1. Check network latency:

    ping api.pipeops.io

  2. Use quiet mode:

    pipeops project list --quiet

  3. Disable verbose logging:

    export PIPEOPS_LOG_LEVEL=error

High Memory Usage​

Problem: CLI uses excessive memory.

Solution:

This is usually not an issue with the CLI itself. Check:

  1. Running processes
  2. System memory availability
  3. Consider using Docker for isolation

Debugging​

Enable Debug Logging​

# Set log level
export PIPEOPS_LOG_LEVEL=debug

# Or use flag
pipeops project list --verbose

Capture Debug Information​

# Capture all output
pipeops project list --verbose > output.log 2>&1

# Or separate stdout and stderr
pipeops project list --verbose > output.log 2> errors.log

Check CLI Version​

pipeops --version

Verify Configuration​

# Show current configuration
cat ~/.pipeops.json | jq .

# Show environment variables
env | grep PIPEOPS

Getting Help​

Built-in Help​

# General help
pipeops --help

# Command-specific help
pipeops list --help
pipeops status --help
pipeops logs --help

Check API Status​

Visit the PipeOps status page or:

curl https://api.pipeops.io/health

Community Support​

Contact Support​

For persistent issues:

Common Error Messages​

ErrorCauseSolution
command not found: pipeopsCLI not in PATHAdd to PATH or reinstall
not authenticatedNo valid auth tokenRun pipeops auth login
token expiredAuth token expiredRe-authenticate
project not foundInvalid project nameCheck project name with project list
permission deniedInsufficient permissionsUse sudo or check file permissions
connection refusedAPI unreachableCheck network/firewall
invalid configurationCorrupt config fileReset configuration

Still Having Issues?​

If you've tried the solutions above and still have problems:

  1. Collect debug information:

    pipeops --version
    pipeops auth status
    cat ~/.pipeops.json
    env | grep PIPEOPS

  2. Create a minimal reproduction:

    # Document exact steps to reproduce
    pipeops auth login
    pipeops project list
    # etc.

  3. Contact support with:

    • CLI version
    • Operating system
    • Error messages
    • Steps to reproduce
    • Debug logs (with sensitive data removed)

See Also​