Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
546 lines (412 loc) · 9.14 KB

TROUBLESHOOTING.md

File metadata and controls

546 lines (412 loc) · 9.14 KB
Raw

Troubleshooting Guide

Common issues and solutions for Pup CLI.

Authentication Issues

OAuth2 Login Fails

Symptoms:

Error: failed to complete OAuth login

Common causes:

  1. Network connectivity

    # Test connectivity to Datadog
curl -I https://datadoghq.com

# Check DNS resolution
nslookup datadoghq.com

  2. Firewall blocking localhost

    • Callback server needs to bind to 127.0.0.1:<random-port>
    • Check firewall allows connections to localhost
    • Try temporarily disabling firewall

  3. Browser doesn't open

    ⚠️  Could not open browser automatically
Please open this URL manually: https://...
    • Copy URL and paste in browser manually
    • Check $BROWSER environment variable
    • Try setting: export BROWSER=chrome

  4. Port already in use

    • CLI automatically tries random available port
    • If error persists, check for port conflicts:
    # List processes listening on local ports
lsof -i -P | grep LISTEN | grep 127.0.0.1

Solutions:

# Try with verbose logging
pup --verbose auth login

# Specify site explicitly
pup --site=datadoghq.com auth login

# Check authentication status
pup auth status

Token Refresh Fails

Symptoms:

Error: failed to refresh access token
⚠️  Token expired. Run 'pup auth refresh' or 'pup auth login'

Causes:

  • Refresh token expired (30-day lifetime)
  • Network connectivity lost
  • OAuth client revoked
  • Invalid stored tokens

Solutions:

# Try manual refresh
pup auth refresh

# If refresh fails, re-authenticate
pup auth logout
pup auth login

# Check stored tokens (debug only)
ls -la ~/.config/pup/tokens_*.json

Keychain Access Denied

macOS symptoms:

Warning: keychain access denied, using encrypted file storage

Solutions:

  1. Grant keychain access:

    • Open "Keychain Access" app
    • Search for "pup"
    • Right-click → "Get Info"
    • Grant access to pup binary

  2. Use fallback storage:

    • Pup automatically falls back to encrypted file
    • Check: ~/.config/pup/tokens.enc
    • File permissions should be 0600

API Key Authentication Fails

Symptoms:

Error: authentication failed: 403 Forbidden

Check environment variables:

# Verify keys are set
echo $DD_API_KEY
echo $DD_APP_KEY
echo $DD_SITE

# Set if missing
export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"
export DD_SITE="datadoghq.com"

Validate keys:

# Test with curl
curl -X GET "https://api.datadoghq.com/api/v1/validate" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

API Call Issues

Rate Limiting

Symptoms:

Error: 429 Too Many Requests
Rate limit exceeded

Solutions:

  • Wait before retrying
  • Reduce number of concurrent requests
  • Check your Datadog plan limits
  • Use pagination with smaller page sizes

Workaround:

# Add delay between requests
for id in $(cat ids.txt); do
  pup monitors get "$id"
  sleep 1  # Wait 1 second between requests
done

Timeout Errors

Symptoms:

Error: context deadline exceeded
Error: request timeout

Causes:

  • Network latency
  • Large result set
  • Datadog API slow response

Solutions:

# Use pagination
pup monitors list --limit=100

# Use shorter time ranges
pup logs search --query="..." --from="30m"  # Instead of 24h

# Check network latency
ping api.datadoghq.com

404 Not Found

Symptoms:

Error: 404 Not Found
Resource not found: monitor 12345678

Causes:

  • Resource deleted
  • Wrong resource ID
  • Wrong Datadog site
  • Insufficient permissions

Solutions:

# Verify resource exists
pup monitors list | grep "12345678"

# Check you're on correct site
pup --verbose monitors get 12345678

# Try with different site
pup --site=datadoghq.eu monitors get 12345678

Command Issues

Command Not Found

Symptoms:

Error: unknown command "foo" for "pup"

Solutions:

# List available commands
pup --help

# Check command spelling
pup metrics --help

# Verify command exists
pup help metrics query

Invalid Flags

Symptoms:

Error: unknown flag: --foo

Solutions:

# Check available flags
pup metrics query --help

# Common flag mistakes:
pup metrics query --query="..." --from="1h"  # Correct
pup metrics query -query="..." -from="1h"    # Wrong (single dash)

Missing Required Flags

Symptoms:

Error: required flag "query" not set

Solutions:

# Check required flags in help
pup metrics query --help

# Provide required flags
pup metrics query --query="avg:system.cpu.user{*}" --from="1h"

Build Issues

Compilation Errors

Symptoms:

# go build
./cmd/foo.go:123: undefined: SomeType

Solutions:

# Clean and rebuild
go clean
go mod tidy
go build -o pup .

# Update dependencies
go get -u github.com/DataDog/datadog-api-client-go/v2
go mod tidy

Missing Dependencies

Symptoms:

go: missing go.sum entry for module

Solutions:

# Download missing dependencies
go mod download

# Regenerate go.sum
go mod tidy

# Verify module checksums
go mod verify

Test Failures

Symptoms:

FAIL: TestSomething

Solutions:

# Run tests with verbose output
go test -v ./...

# Run specific test
go test -v ./pkg/auth/... -run TestOAuthFlow

# Run with race detection
go test -race ./...

# Check test coverage
go test -cover ./...

Output Issues

JSON Parse Errors

Symptoms:

Error: invalid character '<' looking for beginning of value

Causes:

  • HTML error response instead of JSON
  • API returned non-JSON
  • Corrupted response

Solutions:

# Check raw response
pup --verbose monitors list

# Try different output format
pup monitors list --output=yaml

Table Formatting Issues

Symptoms:

  • Columns misaligned
  • Text truncated
  • Wide output

Solutions:

# Use JSON for complete output
pup monitors list --output=json | jq .

# Specify custom fields
pup monitors list --fields="id,name,status"

# Use YAML for readability
pup monitors list --output=yaml

Performance Issues

Slow Commands

Causes:

  • Large result sets
  • Wide time ranges
  • Network latency
  • Datadog API slow response

Solutions:

# Use pagination
pup monitors list --limit=50

# Narrow time range
pup logs search --from="30m"  # Instead of 24h

# Filter results
pup monitors list --tag="env:prod"  # Instead of all

High Memory Usage

Causes:

  • Loading large result sets
  • Not using pagination
  • Processing too much data

Solutions:

# Use streaming/pagination
pup monitors list --limit=100

# Process in batches
for page in {0..10}; do
  pup monitors list --offset=$((page * 100)) --limit=100
done

Debug Mode

Enable verbose logging to troubleshoot issues:

# Global verbose flag
pup --verbose <command>

# Set log level via env var
export PUP_LOG_LEVEL=debug
pup <command>

# Trace HTTP requests
export DD_DEBUG=true
pup --verbose <command>

Verbose output includes:

  • HTTP request details
  • API endpoint URLs
  • Authentication method used
  • Response status codes
  • Error stack traces

Configuration Issues

Config File Not Loaded

Check locations:

# Default location
ls -la ~/.config/pup/config.yaml

# Custom location
pup --config=/path/to/config.yaml <command>

# Verify config syntax
cat ~/.config/pup/config.yaml | yq .

Environment Variable Conflicts

Precedence order:

  1. Command flags (highest)
  2. Environment variables
  3. Config file
  4. Defaults (lowest)

Debug config:

# Show resolved config
pup --verbose auth status

# Check env vars
env | grep DD_
env | grep PUP_

Getting Help

Documentation

  1. Check command help:

    pup --help
pup metrics --help
pup metrics query --help

  2. Read documentation:

  3. Check API docs:

Reporting Issues

When opening a GitHub issue, include:

  1. Pup version:

    pup --version

  2. Command that failed:

    pup --verbose <command>

  3. Environment info:

    # OS version
uname -a

# Go version
go version

# Environment variables (redact keys!)
env | grep DD_SITE

  4. Error message and stack trace

  5. Steps to reproduce

  6. Expected vs actual behavior

Community Support

Common Workarounds

Bypass SSL Verification (Not Recommended)

Only for testing with self-signed certs:

export DD_SKIP_SSL_VALIDATION=true
pup <command>

Use Proxy

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
pup <command>

Override API Endpoint

For testing or custom deployments:

export DD_HOST=https://custom-api.example.com
pup <command>