Skip to main content

​
Troubleshooting

Quick solutions to common issues.

​
Authentication Errors

​
”401 Unauthorized”

Cause: Missing or invalid API key. Fix: 
# Check your key is set
echo $TREESHIP_API_KEY

# Verify it's valid
curl https://api.treeship.dev/v1/keys/info \
  -H "Authorization: Bearer $TREESHIP_API_KEY"
If the key is invalid, generate a new one.

​
”403 Forbidden”

Cause: API key has been revoked or rate limited. Fix: Check your key status or generate a new one: 
curl -X POST https://api.treeship.dev/v1/keys/request \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

​
Rate Limiting

​
”429 Too Many Requests”

Cause: Exceeded rate limits (1000/day or 100/minute). Fix:
  1. Check current usage: 
    curl https://api.treeship.dev/v1/keys/info \
  -H "Authorization: Bearer $TREESHIP_API_KEY"
  2. Implement exponential backoff
  3. Batch attestations if possible
  4. Contact us for higher limits

​
Verification Failures

​
”Signature verification failed”

Causes:
  • Attestation was tampered with
  • Wrong public key
  • Data corruption
Fix:
  1. Fetch fresh copy from API: 
    curl https://api.treeship.dev/v1/verify/{attestation_id}
  2. Verify you’re using the correct public key: 
    curl https://api.treeship.dev/v1/pubkey
  3. If using cached data, clear cache and retry

​
”Attestation not found”

Cause: Invalid ID or attestation doesn’t exist. Fix: Double-check the attestation ID format (UUID).

​
SDK Issues

​
Python: “ModuleNotFoundError: No module named ‘treeship_sdk’”

Fix: 
pip install treeship-sdk
Note: The package is treeship-sdk (with hyphen), but import is treeship_sdk (with underscore).

​
Python: “Connection refused”

Cause: Network issue or wrong API URL. Fix: 
from treeship_sdk import Treeship

# Check you're using the right URL
ts = Treeship(
    api_key="your-key",
    api_url="https://api.treeship.dev"  # Default
)

​
CLI: “command not found: treeship”

Fix: 
npm install -g treeship-cli

# Verify installation
which treeship
treeship --version

​
CLI: “TREESHIP_API_KEY not set”

Fix: 
# Set in current shell
export TREESHIP_API_KEY=your-key

# Or configure permanently
treeship config set api-key your-key

​
Network Issues

​
Timeouts

Cause: Network latency or firewall issues. Fix:
  1. Check API status: curl https://api.treeship.dev/health
  2. Increase timeout in your client
  3. Check firewall allows HTTPS to api.treeship.dev

​
SSL Certificate Errors

Cause: Outdated CA certificates or MITM proxy. Fix:
  1. Update your system’s CA certificates
  2. If behind corporate proxy, add proxy CA to trust store
  3. Don’t disable SSL verification in production

​
Self-Hosting Issues

​
”No signing key configured”

Cause: Missing TREESHIP_SIGNING_KEY environment variable. Fix: Generate and set a key: 
python -c "from signing import KeyPair; kp = KeyPair.generate(); print(kp.private_key_pem())"
# Set the output as TREESHIP_SIGNING_KEY

​
Database Connection Failed

Cause: SQLite file permissions or PostgreSQL connection string. Fix: 
# For SQLite, ensure directory is writable
mkdir -p data && chmod 755 data

# For PostgreSQL, check connection string
export DATABASE_URL="postgresql://user:pass@host:5432/treeship"

​
Still Stuck?

  1. Check API status
  2. Review FAQ for common questions
  3. Search GitHub issues
  4. Open a new issue with:
    • What you’re trying to do
    • Error messages (full output)
    • Your environment (OS, SDK version)