Troubleshooting

Common issues and their solutions. If your problem isn't listed here, check the FAQ or open an issue on GitHub.

Gateway won't start

Port already in use — Another process is using port 3000. Either stop it or change the port:

bash

# Find what's using the port
lsof -i :3000

# Or start on a different port
HYBRIX_PORT=3001 hybrix start

Missing config file — Hybrix can't find hybrix.config.json. Run hybrix init to create one, or specify the path:

bash

HYBRIX_CONFIG_PATH=./config/hybrix.json hybrix start

Node.js version too old — Hybrix requires Node.js v18+. Check your version:

bash

node --version  # Must be >= 18.0.0

Invalid API key — The most common issue. Verify your key is set and valid:

bash

hybrix env check

Rate limited — Your LLM provider may be throttling requests. Check the gateway logs for 429 status codes:

bash

hybrix logs --level warn

Model not available — The model ID might be incorrect or deprecated. Check your provider's documentation for current model names.

Discord bot offline — Ensure the Message Content Intent is enabled in the Developer Portal. Without it, the bot connects but can't read messages.

Slack events not arriving — Your gateway must be reachable from the internet for Slack webhooks. Use hybrix tunnel for local development.

Telegram webhook failing — Telegram requires HTTPS. Use a reverse proxy with TLS or switch to long polling for development.

Run hybrix channel test <type> to verify a channel connection is working. It sends a test message and confirms the round trip.

Enable verbose logging to see detailed request/response traces, routing decisions, and skill execution details:

bash

HYBRIX_LOG_LEVEL=debug hybrix start

Debug mode outputs every LLM API call, including token counts and latency. This is useful for diagnosing slow responses and unexpected routing.