Troubleshooting

This chapter covers common issues organized by category, along with environment variable reference.

API & Provider Issues

API Key Not Set

Error: ANTHROPIC_API_KEY environment variable not set

Fix: Export the key in your shell or verify with octos status:

export ANTHROPIC_API_KEY="your-key"

If running as a service, ensure the environment variable is set in the service environment (launchd plist or systemd unit), not just your interactive shell.

Rate Limited (429)

The retry mechanism handles this automatically (3 attempts with exponential backoff). If the error persists:

• Try switching to a different provider via /queue or in-chat model switching.
• Wait for the rate limit window to reset.

Debug Logging

Enable detailed logs to diagnose issues:

RUST_LOG=debug octos chat
RUST_LOG=octos_agent=trace octos chat --message "task"

Build Issues

Channel-Specific Issues

Lark / Feishu

WeCom / WeChat

“Environment variable WECOM_BOT_SECRET not set”

Set the secret before starting the gateway:

export WECOM_BOT_SECRET="your_secret"

Connection drops or fails to subscribe

• Verify bot_id and secret are correct.
• Check network connectivity to wss://openws.work.weixin.qq.com.
• The channel auto-reconnects up to 100 times with exponential backoff. Check logs for error details.

Messages not arriving

• Confirm the upstream relay service is running and linked to your account.
• Check that the WeCom group robot is the same one configured in octos.
• If using allowed_senders, verify the sender’s WeCom user ID is in the list.
• Check for duplicate message filtering – the channel deduplicates the last 1000 message IDs.

Long messages are truncated

Messages over 4096 characters are automatically split into multiple chunks by octos. If further truncation occurs, check the relay service’s own message length settings.

Platform-Specific Issues

Environment Variables Reference