Troubleshooting

Use this matrix for common runtime and ops failures.

Troubleshooting matrix

Symptom	Likely cause	Verify	Fix
Telegram bot connected but no response	sender ID not in allowFrom	g-agent status and gateway logs	add numeric Telegram ID to channels.telegram.allowFrom
WhatsApp access denied	WA sender ID mismatch	gateway warning shows rejected sender	add exact sender ID to channels.whatsapp.allowFrom
WhatsApp bridge reconnect loop	stale session or unstable bridge runtime	journalctl --user -u g-agent-wa-bridge.service	re-login via g-agent channels login, restart bridge
Channel silently stops after runtime error	transient channel crash	gateway logs show channel crashed/restarting	upgrade to latest build; supervisor now auto-restarts channels with backoff
Outbound reply missed during reconnect	channel send failed during transient disconnect	gateway logs show Retrying outbound message	keep gateway running; dispatcher now retries failed sends with capped backoff
status / doctor shows metrics alert warnings	SLO threshold breached (success-rate, latency, recall)	g-agent metrics --hours 24	inspect warned checks and fix root cause (provider, tools, cron, recall quality)
LLM auth error	wrong provider key/base/model route	g-agent status, provider section in config	correct providers.* fields and restart gateway
Google tool unavailable	gws binary missing from service PATH	gws auth status locally and check integrations.google.gwsPath	set absolute gwsPath in config and restart gateway
Google auth says credentials.json missing	stale credentialsFile points at a removed plaintext export while gws uses encrypted storage	gws auth status shows credentials.enc and plain_credentials_exists=false	clear integrations.google.credentialsFile and restart gateway
Google auth returns invalid_grant	expired/revoked gws token	/path/to/gws auth status and a direct Gmail/Calendar command	run gws auth logout then gws auth login --services gmail,calendar
Cron jobs not firing	jobs disabled/misconfigured timezone	startup logs + cron service lines	verify proactive config and schedule definitions

Core diagnostics

g-agent status
g-agent doctor --network
journalctl --user -u g-agent-gateway.service -u g-agent-wa-bridge.service -n 200 --no-pager

Safe recovery sequence

systemctl --user daemon-reload
systemctl --user restart g-agent-wa-bridge.service g-agent-gateway.service
g-agent status

Escalation checklist

When filing an issue, include:

• commit hash
• config section involved (redact secrets)
• exact command used
• relevant log excerpt (timestamp + error line)