# ट्रबलशूटिंग FAQ

सामान्य Synapse समस्याओं के समाधान।

## मैं लॉगिन नहीं कर पा रहा

### लक्षण

- `POST /login` 401 लौटाता है
- "Invalid email or password"

### समाधान

1. **ईमेल सही है सत्यापित करें** — केस संवेदनशील
2. **पासवर्ड जाँचें** — न्यूनतम 6 अक्षर
3. **पहले पंजीकरण करें** यदि आपके पास खाता नहीं है: `POST /register`
4. **पासवर्ड रीसेट करें** (यदि SMTP कॉन्फ़िगर है) वेब UI के माध्यम से

## मैंने अपनी Mind Key खो दी

### लक्षण

- मेमोरीज़ एक्सेस नहीं कर सकते
- Mind Key हटा दी गई/खो गई

### समाधान

Mind Keys पुनः प्राप्त नहीं की जा सकतीं। आपको ये करना होगा:

1. JWT प्राप्त करने के लिए लॉगिन करें: `POST /login`
2. Minds की सूची बनाएँ: `GET /minds` (JWT के साथ)
3. नया mind बनाएँ: `POST /minds`
4. नई Mind Key सहेजें
5. (वैकल्पिक) पुराना mind हटाएँ: `DELETE /minds/:id`

**पुराने mind का डेटा खो गया** जब तक आप Mind Key न ढूँढ लें।

## API कॉल्स 401 लौटाते हैं

### लक्षण

- सभी API कॉल्स 401 Unauthorized लौटाते हैं
- "Mind Key fehlt oder ungültig"

### समाधान

1. **हेडर प्रारूप सत्यापित करें**: `Authorization: Bearer mk_...`
2. **जाँचें Mind Key `mk_` से शुरू होती है** (न कि `eyJ` जो JWT है)
3. **सीधे परीक्षण करें**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **Mind Key रद्द हो सकती है** — नया mind बनाएँ

[प्रमाणीकरण](/docs/getting-started/authentication) देखें।

## API कॉल्स 404 लौटाते हैं

### लक्षण

- 404 Not Found
- "Route not found"

### समाधान

> [!CRITICAL]
> एंडपॉइंट पाथ का अनुमान न लगाएँ। केवल `GET /endpoints` में पाथ मौजूद हैं।

1. **वैध एंडपॉइंट्स जाँचें**: `curl https://synapse.schaefer.zone/endpoints`
2. **URL सटीक तुलना करें** — केस संवेदनशील, कोई अनुगामी स्लैश नहीं
3. **HTTP विधि जाँचें** — `GET /memory` बनाम `POST /memory` भिन्न हैं

## API कॉल्स 429 लौटाते हैं

### लक्षण

- 429 Too Many Requests
- "Rate limit exceeded"

### समाधान

1. **हेडर प्रमाणीकरण पर स्विच करें** (कोई रेट लिमिट नहीं):
   ```bash
   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. **यदि आपको `?key=` उपयोग करना ही है तो `Retry-After` सेकंड प्रतीक्षा करें**

[रेट लिमिट](/docs/api/rate-limits) देखें।

## मेमोरी खोज कोई परिणाम नहीं लौटाती

### लक्षण

- `GET /memory/search?q=...` खाली लौटाता है
- जानते हैं मेमोरीज़ मौजूद हैं

### समाधान

1. **मेमोरीज़ मौजूद हैं सत्यापित करें**: `GET /memory/recall`
2. **खोज सिंटैक्स जाँचें** — FTS5 की विशिष्ट सिंटैक्स है
3. **सरल क्वेरी आज़माएँ** — `?q=docker+swarm+deployment` के बजाय `?q=docker`
4. **वैचारिक क्वेरीज़ के लिए सिमेंटिक खोज का उपयोग करें**: `GET /memory/semantic-search?q=...`

[FTS5 Search](/docs/concepts/fts5-search) देखें।

## मेमोरीज़ बनी नहीं रह रहीं

### लक्षण

- POST /memory success लौटाता है
- GET /memory/recall उन्हें नहीं दिखाता

### समाधान

1. **समान Mind Key सत्यापित करें** — भिन्न कुंजी = भिन्न minds
2. **प्रतिक्रिया जाँचें** — POST `{ "id": "mem_...", "status": "stored" }` लौटाता है
3. **/memory/recall (टेक्स्ट) के बजाय GET /memory (JSON सूची) आज़माएँ**
4. **फ़िल्टर जाँचें** — `?category=` या `?tag=` उन्हें छिपा सकते हैं

## Claude Desktop में टूल्स दिखाई नहीं दे रहे

### लक्षण

- Claude Desktop 0 टूल्स दिखाता है
- कोई 🔌 आइकन नहीं

### समाधान

1. **Claude Desktop पूरी तरह रीस्टार्ट करें** (Cmd+Q)
2. **सत्यापित करें कॉन्फ़िग फ़ाइल** वैध JSON है
3. **Node.js 18+ इंस्टॉल जाँचें**
4. **MCP मैन्युअली चलाएँ**: `npx -y synapse-mcp-api@latest`
5. **लॉग जाँचें**: `~/Library/Logs/Claude/mcp.log`

[MCP ट्रबलशूटिंग](/docs/mcp/troubleshooting) देखें।

## Synapse ऑफ़लाइन है

### लक्षण

- synapse.schaefer.zone तक नहीं पहुँच सकते
- curl समय समाप्त होता है

### समाधान

1. **अपना इंटरनेट जाँचें** — किसी अन्य साइट का प्रयास करें
2. **Synapse स्वास्थ्य जाँचें**: `curl https://synapse.schaefer.zone/health`
3. **प्रतीक्षा करें** — अस्थायी आउटेज या परिनियोजन हो सकता है
4. **स्टेटस पृष्ठ जाँचें** (यदि उपलब्ध हो)

सेल्फ-होस्टेड के लिए: Docker कंटेनर स्थिति, डेटाबेस कनेक्शन जाँचें।

## डेटाबेस त्रुटियाँ

### लक्षण

- 500 Internal Server Error
- "Database connection failed"

### समाधान

सेल्फ-होस्टेड के लिए:

1. **PostgreSQL चल रहा है जाँचें**: `docker ps | grep postgres`
2. **env में DATABASE_URL जाँचें**
3. **माइग्रेशन जाँचें**: `npm run migrate:check`
4. **डिस्क स्थान जाँचें**: `df -h`

होस्टेड के लिए: सहायता को रिपोर्ट करें।

## Webhook सक्रिय नहीं हो रहा

### लक्षण

- Webhook पंजीकृत किया लेकिन कॉलबैक नहीं मिल रहे
- आपके URL पर कोई POST नहीं

### समाधान

1. **URL पहुँच योग्य है सत्यापित करें**: `curl -X POST your-url -d '{}'`
2. **events फ़िल्टर जाँचें** — `memory.*` सभी मेमोरी घटनाओं से मेल खाता है
3. **webhook परीक्षण**: `POST /webhooks/:id/test`
4. **webhook सक्षम है जाँचें**: `GET /webhooks/:id`
5. **SSL सत्यापित करें** — Synapse को webhook URLs के लिए वैध HTTPS चाहिए

[Webhooks API](/docs/api/webhooks) देखें।

## Cron कार्य नहीं चल रहा

### लक्षण

- Cron कार्य बनाया लेकिन सक्रिय नहीं हो रहा
- `next_run` अपडेट नहीं हो रहा

### समाधान

1. **शेड्यूल सिंटैक्स जाँचें** — वैध 5-फ़ील्ड cron या पूर्णांक सेकंड होना चाहिए
2. **एंडपॉइंट अनुमत है सत्यापित करें** — http(s) होना चाहिए, कोई निजी IP नहीं
3. **कार्य सक्षम है जाँचें**: `GET /cron`
4. **अगले शेड्यूल किए गए समय की प्रतीक्षा करें** — cron तुरंत नहीं होता

[Cron और Scheduler](/docs/api/cron) देखें।

## और सहायता चाहिए?

1. **मौजूदा दस्तावेज़ जाँचें**: <https://synapse.schaefer.zone/docs>
2. **दस्तावेज़ खोजें**: `GET /docs/search?q=your+question`
3. **Issue खोलें**: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. **संपर्क**: `/support` पृष्ठ देखें

## अगले कदम

- [त्रुटियाँ और त्रुटि प्रबंधन](/docs/api/errors)
- [API FAQ](/docs/faq/api-faq)
- [MCP ट्रबलशूटिंग](/docs/mcp/troubleshooting)