Troubleshooting

Common issues with Kite installation, authentication, webhook delivery, and the CLI.

// 01Authentication issues

kite login — browser doesn't open

Run with --server to verify the server URL:

kite login --server https://getkite.sh

If you're in a headless environment, the device code is printed to the terminal. Navigate to the verification URL on another device.

"Invalid or expired API key"

Your API key may have been rotated or revoked. Re-authenticate:

kite login

Or set a fresh key via the environment variable:

export KITE_API_KEY=kit_live_...

// 02Webhook delivery issues

No events arriving

1. Verify your endpoint is active: kite endpoints list 2. Check the source webhook URL in your provider's dashboard matches the Kite relay URL 3. Confirm the signing secret is set correctly. For GitHub, rotate with kite endpoints create --source github or kite github install --repo owner/repo --rotate-secret. For providers such as Linear or Stripe, paste the provider-issued secret into Kite when creating or rotating the endpoint. 4. Check kite logs --limit 20 for any delivery errors

Events arrive but fail in your handler

Failed deliveries land in the dead letter queue. Inspect and retry:

kite logs --limit 50
kite retry --target http://localhost:3000/webhooks

Signature verification failures

Provider-verified sources reject webhooks when the signature check fails. Common causes:

• Mismatched signing secret — rotate the endpoint and update either Kite or the provider with the new shared secret
• Payload was modified in transit (proxies that re-encode JSON)
• Clock skew (Stripe requires timestamp within 300 seconds)

// 03CLI issues

"command not found: kite"

The binary may not be on your PATH. Check:

ls /usr/local/bin/kite
which kite

Re-run the install script:

curl -sSL https://getkite.sh/install | sh

Stale binary — update

kite update
kite update --check  # check without installing

Permission denied on install

The script tries to write to /usr/local/bin. If you don't have write access:

curl -sSL https://getkite.sh/install | KITE_INSTALL_DIR=~/.local/bin sh
export PATH="$HOME/.local/bin:$PATH"

// 04Getting help

• Check kite <command> --help for command-specific options
• Open an issue at github.com/Alpha-Centauri-Cyberspace/kite-cli
• Email support from the dashboard