Troubleshooting

License Issues

"License validation failed"

  • Check your internet connection — the binary contacts api.openalloy.ai for validation
  • Verify your license key: openalloy config get license_key
  • Re-activate: openalloy activate --key OA-XXXX-XXXX-XXXX
  • If the issue persists, check your license status at Dashboard

"License expired"

Enterprise subscriptions require an active payment. Check your subscription status at Dashboard or contact support.

Provider Errors

"API key invalid" / 401 errors

  • Verify the key is set: openalloy config get <provider>.api_key
  • Ensure the key has the correct permissions (some providers require specific scopes)
  • Try regenerating the key from the provider's dashboard

Rate limiting

If you hit rate limits, OpenAlloy will automatically retry with exponential backoff. To switch to a different provider:

openalloy config set default.provider <alternative>

Model not found

# List available models for a provider
openalloy models --provider anthropic

WhatsApp Daemon

QR code not appearing

  • Ensure your terminal supports Unicode and is wide enough (80+ columns)
  • Try: openalloy daemon --whatsapp --verbose

Messages not being processed

  • Check logs: tail -f ~/.config/openalloy/logs/whatsapp.log
  • Verify allowed contacts: openalloy config get whatsapp.allowed_contacts
  • Ensure the LLM provider API key is valid

Session expired

WhatsApp sessions expire after 14 days of inactivity. Re-scan the QR code:

openalloy daemon --whatsapp --reauth

General

Binary won't start

  • Verify the binary is executable: chmod +x openalloy
  • On macOS, you may need to allow it in System Settings > Security & Privacy
  • Check architecture: file openalloy should match your CPU (arm64/amd64)

Config file issues

Reset to defaults:

openalloy config reset

Verbose logging

openalloy chat --verbose
# or
export OPENALLOY_LOG=debug
openalloy chat

Getting Help

API Reference