Troubleshooting

सामान्य issues और उन्हें कैसे resolve करें।

Gateway Issues

Gateway start नहीं होगा

• Port conflict, कोई अन्य process port 18789 उपयोग कर रहा हो सकता है। lsof -i :18789 से check करें।
• Config error, neotask.json में invalid JSON। Gateway startup पर config validate करता है और specific errors report करता है।
• Gateway lock, एक previous instance ने stale lock file छोड़ी हो सकती है। Diagnostic tool इसे detect और fix कर सकता है।
• Node.js version, Neotask को Node 22+ आवश्यक है।

Gateway start होता है लेकिन कोई channels connect नहीं होते

• Missing credentials, प्रत्येक channel को अपनी own auth आवश्यक है (bot token, QR scan, API key)।
• Network issues, Channels को messaging platform APIs से connect होने के लिए internet access आवश्यक है।
• Rate limits, कुछ platforms new connections को rate-limit करते हैं। Wait करें और retry करें।

Desktop app से connect नहीं हो सकता

• Wrong port, सुनिश्चित करें कि desktop app सही Gateway port से connect हो रहा है।
• Auth mismatch, Gateway token match होना चाहिए।
• Firewall, सुनिश्चित करें कि port accessible है यदि Gateway दूसरी machine पर है।

Channel Issues

WhatsApp connect नहीं होगा

• QR expired, QR codes ~60 seconds के बाद expire हो जाते हैं। Quickly re-scan करें।
• Multi-device limit, WhatsApp linked devices limit करता है।
• Session corrupted, WhatsApp session directory delete करें और re-pair करें।

Telegram bot messages receive नहीं कर रहा

• Bot token invalid, BotFather से अपना bot token verify करें।
• Privacy mode, Default रूप से Bots केवल groups में mention किए जाने पर messages देखते हैं।
• Webhook conflict, कोई अन्य service messages consume कर रही हो सकती है।

Discord bot respond नहीं कर रहा

• Missing intents, Discord Developer Portal में required Gateway Intents enable करें।
• Missing permissions, Bot को target channels में read और send permissions चाहिए।

Model Issues

Auth errors

• Key not configured, सुनिश्चित करें कि provider API key set है।
• Key expired, कुछ OAuth tokens expire हो जाते हैं। Re-authenticate करें।
• Rate limit, यदि आपके पास multiple keys हैं तो Key rotation automatically switch करेगी।

Slow responses

• Model choice, Larger models slower हैं। Quick tasks के लिए faster model try करें।
• Context size, Long conversations processing slow करती हैं। /compact try करें।
• Network latency, अपने model provider से connectivity check करें।

Node Issues

Companion app Gateway नहीं ढूंढ पा रहा

• Binding mode, External devices के लिए Gateway LAN या Tailnet से bound होना चाहिए (loopback नहीं)।
• Same network, Bonjour discovery के लिए, दोनों devices same network पर होने चाहिए।
• Manual entry, App settings में Gateway host और port manually enter करें।

Session Issues

Context window exceeded

• Compact, Context summarize और reset करने के लिए /compact उपयोग करें।
• Enable auto-compaction, Config में compaction threshold set करें।
• New session, /new से fresh start करें।

Diagnostics

Built-in diagnostic tool common issues check करता है और कई automatically fix कर सकता है:

• Config validation
• File permissions
• Channel connectivity
• Model auth status
• Node.js compatibility
• Network configuration

Detailed error information के लिए Gateway logs check करें। /health endpoint सभी components का machine-readable status provide करता है।

Help पाना

1. Automated fixes के लिए diagnostic tool run करें
2. Detailed error messages के लिए Gateway logs check करें
3. Desktop app में Intercom chat widget के माध्यम से support से contact करें