> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# समस्या निवारण

> AgentEye समस्या निवारण दस्तावेज़।

यह गाइड आपको उत्पादन में सबसे अधिक संभावित समस्याओं को ठोस निदान और समाधान से जोड़ता है, ताकि आप अतिरिक्त अवलोकन बुनियादी ढांचे को सेट किए बिना पहले से मौजूद उपकरणों से घटनाओं को हल कर सकें। यह सर्वर, कलेक्टर, डैशबोर्ड, एआई असिस्टेंट, Python SDK, स्वास्थ्य और प्रमाणपत्र निगरानी, बैकअप, ClickHouse-समर्थित विश्लेषण और बहु-किरायेदारी को कवर करता है।

डैशबोर्ड पृष्ठ `/<org-slug>/…` के तहत संगठन-स्कोप किए गए हैं, और इवेंट्स स्ट्रीम संगठन मुखपृष्ठ है (`/<org-slug>/`)। इस गाइड में पृष्ठ के नाम (उदाहरण के लिए `/sessions`, `/queries`) उन संगठन-स्कोप किए गए मार्गों को संदर्भित करते हैं।

***

## लॉग्स देखना

AgentEye एक लॉगिंग या निगरानी स्टैक बंडल नहीं करता है। सर्वर और डैशबोर्ड दोनों **stdout** में संरचित लॉग्स लिखते हैं, इसलिए आप उन्हें `kubectl` या `docker` से सीधे पढ़ सकते हैं; कोई एकत्रकर्ता आवश्यक नहीं है।

### Kubernetes

सर्वर और डैशबोर्ड के लिए लाइव लॉग्स का पालन करें:

```bash theme={null}
kubectl logs -n agenteye -l app=server    -f --timestamps
kubectl logs -n agenteye -l app=dashboard -f --timestamps
```

उपयोगी वेरिएंट:

| लक्ष्य                              | कमांड                                                             |
| ----------------------------------- | ----------------------------------------------------------------- |
| पिछली 200 लाइनें (कोई पालन नहीं)    | `kubectl logs -n agenteye -l app=server --tail=200 --timestamps`  |
| पिछले क्रैश से लॉग्स                | `kubectl logs -n agenteye <pod-name> --previous`                  |
| सभी प्रतिकृतियों को एक बार टेल करें | `kubectl logs -n agenteye -l app=server --max-log-requests=10 -f` |
| Postgres (StatefulSet)              | `kubectl logs -n agenteye postgres-0 -f`                          |

### Docker Compose

```bash theme={null}
docker logs -f agenteye-server
docker logs -f agenteye-dashboard
```

### डैशबोर्ड और सर्वर भर में एक अनुरोध को जोड़ना

हर डैशबोर्ड अनुरोध एक `request_id` से टैग किया जाता है और `x-request-id` हेडर के माध्यम से सर्वर को प्रचारित किया जाता है। सर्वर इसे अपने प्रतिक्रिया हेडर में और उस अनुरोध के लिए उत्सर्जित हर लॉग लाइन में दोहराता है। एक अनुरोध को अंत-से-अंत ट्रेस करने के लिए:

1. प्रतिक्रिया हेडर से आईडी कैप्चर करें, उदाहरण के लिए:
   ```bash theme={null}
   curl -i https://dashboard.example.com/api/events | grep -i x-request-id
   # x-request-id: 9a7b0d6e-5e9b-4c0a-9f8a-5f1e4b5c0f3a
   ```
2. उस आईडी के लिए दोनों पॉड्स के लॉग्स को grep करें:
   ```bash theme={null}
   REQ=9a7b0d6e-5e9b-4c0a-9f8a-5f1e4b5c0f3a
   kubectl logs -n agenteye -l app=dashboard --tail=5000 | grep "$REQ"
   kubectl logs -n agenteye -l app=server    --tail=5000 | grep "$REQ"
   ```

आप डैशबोर्ड की `proxy passthrough`, `withAuth: authorized`, और `upstream response` लाइनें देखेंगे, साथ ही सर्वर की `http request received` / `http request completed` जोड़ी, सभी एक ही `request_id` साझा करते हुए।

### JSON लॉग्स और `jq`

डैशबोर्ड पर `AE_LOG_JSON=1` सेट करें (यह डिफ़ॉल्ट रूप से चालू है जब `NODE_ENV=production`) एक JSON ऑब्जेक्ट प्रति लाइन उत्सर्जित करने के लिए। फिर संरचनात्मक रूप से फ़िल्टर करें:

```bash theme={null}
kubectl logs -n agenteye -l app=dashboard --tail=5000 \
  | jq 'select(.level == "warn" or .level == "error")'

kubectl logs -n agenteye -l app=dashboard --tail=5000 \
  | jq 'select(.route == "POST /api/keys")'
```

Rust सर्वर tracing `key=value` जोड़ी उत्सर्जित करता है जो `jq` के बिना अच्छी तरह से grep करते हैं:

```bash theme={null}
kubectl logs -n agenteye -l app=server --tail=5000 | grep 'status=5'   # 5xx
kubectl logs -n agenteye -l app=server --tail=5000 | grep 'actor_key_id='
```

### वर्बोसिटी को बढ़ाना

| घटक      | पर्यावरण चर    | उदाहरण                                                    |
| -------- | -------------- | --------------------------------------------------------- |
| सर्वर    | `RUST_LOG`     | `RUST_LOG=debug` या `RUST_LOG=agenteye_server=debug,info` |
| डैशबोर्ड | `AE_LOG_LEVEL` | `AE_LOG_LEVEL=debug`                                      |

सर्वर पर `debug` प्रति-प्रमाणीकरण `api key authenticated` लाइन जोड़ता है। डैशबोर्ड पर `debug` `upstream request`, `session validated`, और `proxy passthrough` लाइनें जोड़ता है।

### लॉग प्रतिधारण

कंटेनर stdout अस्थायी है; kubelet लॉग फ़ाइलों को घुमाता है (डिफ़ॉल्ट \~10 MiB प्रति कंटेनर) और डिस्क पर कुछ रखता है। एक बार पॉड हटाए जाने के बाद लॉग्स चले जाते हैं। यदि आपको लंबी प्रतिधारण या क्रॉस-पॉड खोज की आवश्यकता है, तो अपने क्लस्टर को एक लॉग कलेक्टर (Loki, CloudWatch, Cloud Logging, Datadog, आदि) की ओर इंगित करें जो `/var/log/containers/` को टेल करता है। AgentEye किसी विशिष्ट विकल्प की आवश्यकता या निर्धारण नहीं करता है।

***

## प्रमाणीकरण समस्याएं

### `docker pull` "unauthorized" के साथ विफल होता है

सुनिश्चित करें कि आपने अपने `AGENTEYE_TOKEN` के साथ GHCR के विरुद्ध Docker को प्रमाणित किया है:

```bash theme={null}
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
```

टोकन में `agenteye-enterprise` संगठन पर `read:packages` अनुमति होनी चाहिए। यदि आपका टोकन काम नहीं करता है तो `support@exosphere.host` से संपर्क करें।

### `gh release download` 404 या 401 देता है

* पुष्टि करें कि `AGENTEYE_TOKEN` आपके शेल में निर्यात किया गया है: `echo $AGENTEYE_TOKEN`
* पुष्टि करें कि आप `GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download ...` का उपयोग कर रहे हैं (the `gh` CLI `GITHUB_TOKEN` को पढ़ता है)
* टोकन को `agenteye-enterprise/releases` पर `contents:read` की आवश्यकता है

***

## सर्वर समस्याएं

### सर्वर "invalid port number" के साथ विफल होता है

`POSTGRES_PASSWORD` (या अन्य क्रेडेंशियल) में URL-विशेष वर्ण (`/`, `+`, `=`) हैं जो `DATABASE_URL` पार्सिंग को तोड़ते हैं। हेक्स एन्कोडिंग का उपयोग करके पासवर्ड पुनः उत्पन्न करें:

```bash theme={null}
NEW_PASS=$(openssl rand -hex 24)
```

फिर Kubernetes गोपनीयता और Postgres के अंदर पासवर्ड को अपडेट करें (या Docker Compose के लिए `.env` को पुनः बनाएं), और सर्वर को पुनरारंभ करें। [enterprise-docs/kubernetes-deployment.md](/hi/agenteye/kubernetes-deployment) § "PostgreSQL credentials" में पूर्ण चरण देखें।

### सर्वर स्टार्टअप पर तुरंत बाहर निकलता है

कंटेनर लॉग्स जांचें:

```bash theme={null}
docker logs agenteye-server
```

सामान्य कारण:

* `DATABASE_URL` सेट नहीं है या विकृत है: सर्वर त्रुटि लॉग करेगा और बाहर निकलेगा।
* Postgres पहुंच योग्य नहीं है: पुष्टि करें कि Postgres कंटेनर या प्रबंधित DB चल रहा है और होस्ट/पोर्ट सही हैं।
* माइग्रेशन विफल हुए: SQL त्रुटियों के लिए लॉग्स जांचें।

### `GET /health` गैर-200 या टाइमआउट देता है

सर्वर पहली शुरुआत पर अभी भी माइग्रेशन चलाया जा रहा है। कुछ सेकंड प्रतीक्षा करें और पुनः प्रयास करें:

```bash theme={null}
curl http://localhost:8080/health
```

यदि समस्या बनी रहती है, तो त्रुटियों के लिए `docker logs agenteye-server` जांचें।

### `GET /ready` 503 देता है

`/ready` readiness जांच है: यह 503 देता है जब सर्वर **Postgres या ClickHouse** तक पहुंच नहीं सकता है। शरीर विफल निर्भरता का नाम बताता है:

```bash theme={null}
curl -s http://localhost:8080/ready
# {"status":"not_ready","checks":{"postgres":"ok","clickhouse":"down","redis":"ok"}}
```

जो निर्भरता यह `down` के रूप में रिपोर्ट करता है उसे ठीक करें: क्या ClickHouse/Postgres पॉड `Running` है? क्या `CLICKHOUSE_URL` / `DATABASE_URL` सही और पहुंच योग्य है? Kubernetes पर पॉड `NotReady` पढ़ता है जब तक `/ready` ठीक नहीं होता; यह अपेक्षित है और बिल्कुल वह संकेत है जो स्वास्थ्य निगरानी सतर्क करता है। Redis कभी कारण नहीं है: यह रिपोर्ट किया जाता है लेकिन readiness को विफल नहीं करता।

### कलेक्टर 401 Unauthorized देता है

कलेक्टर की API कुंजी के पास `events:add` अनुमति नहीं है, या कुंजी को अक्षम किया गया है। सही अनुमति के साथ एक नई कुंजी बनाएं:

```bash theme={null}
curl -s -X POST http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-collector","permissions":["events:add"]}'
```

### प्रमाणित अनुरोध अचानक धीमे हो गए (\~200ms के बजाय \~5ms)

यह Redis के नीचे होने का लक्षण है जबकि `REDIS_URL` सेट है। हर कैश कॉल 100ms के बाद टाइमआउट करता है फिर Postgres में गिरता है; प्रमाणीकरण और OTP पथों पर अनुरोध दो ऐसे पतन बनाता है।

सर्वर लॉग्स में पुष्टि करें:

```
auth cache: L2 get failed error=redis call timed out
```

समाधान:

1. `redis-cli -h <your-redis> ping` क्लस्टर नेटवर्क पर Redis पहुंच योग्य है यह पुष्टि करने के लिए।
2. यदि Redis संक्षिप्त रूप से नीचे था और अब वापस है, तो **सर्वर पॉड्स को पुनरारंभ करें**। `redis::aio::ConnectionManager` अंतर्निहित कनेक्शन गिरने के बाद विश्वसनीय रूप से पुनः स्थापित नहीं करता; पॉड रीस्टार्ट नई कनेक्शन को साफ-सुथरे तरीके से उठाता है। डैशबोर्ड पर भी वही लागू होता है।
3. यदि आप अभी Redis नहीं चलाना चाहते हैं, तो तैनाती में `REDIS_URL` को अनसेट करें और पुनरारंभ करें। दोनों सेवाएं कैश के बिना चलती हैं (शुद्धता संरक्षित है; विलंबता Redis-पूर्व आधारभूत पर वापस आता है)।

### सर्वर लॉग्स में `OTP request rate-limited` रिपोर्ट करता है लेकिन उपयोगकर्ता कहता है कि वे केवल एक बार प्रयास करते हैं

जांचें कि क्या Redis अपहुंच्य था। फॉलबैक पथ `SELECT COUNT(*) FROM otp_codes WHERE created_at > now() - interval '15 minutes'` का उपयोग करता है, जो पहले से उत्पन्न OTP पंक्तियों को देखता है। यदि उपयोगकर्ता एक घंटे के लिए "Resend" पर क्लिक-स्पैम कर रहा है, तो 15-मिनट की विंडो में अभी भी ≥5 कोड हो सकते हैं। विंडो के रोल-ओवर के लिए प्रतीक्षा करके या `DELETE FROM otp_codes WHERE user_id = $1 AND created_at > now() - interval '15 minutes'` (ऑपरेटर कंसोल) को समाधान करें।

### मैंने `ALLOWED_EMAILS` / `SESSION_TTL_SECS` / `OTP_TTL_SECS` बदला और पुनरारंभ किया; कुछ नहीं हुआ

ये env वेरिएबल्स **पहली बूट सीड्स केवल** हैं। एक बार `settings` तालिका में मिलान कुंजी के लिए एक पंक्ति होने के बाद, वह पंक्ति सत्य का स्रोत है; env वेरिएबल पहली बूट पर एक बार पढ़ा जाता है और फिर हर बाद की रीस्टार्ट पर अनदेखा किया जाता है।

पहली बूट के बाद उन्हें बदलने के लिए, डैशबोर्ड में लॉगिन करें और `/settings` के तहत उन्हें संपादित करें। परिवर्तन सभी प्रतिकृतियों भर में सेकंड के भीतर लागू होता है; कोई रीस्टार्ट आवश्यक नहीं है।

यदि आप env से पुनः-सीड को बल देने की आवश्यकता है (दुर्लभ, आमतौर पर विकास में केवल उपयोगी), `DELETE FROM settings WHERE key = '<key>'` और सर्वर को पुनरारंभ करें। बूटस्ट्रैप अगली बूट पर वर्तमान env-var मान लेगा। `/settings` के माध्यम से संपादित करना उत्पादन में समर्थित पथ है।

***

## कलेक्टर समस्याएं

### कलेक्टर शुरू होता है लेकिन इवेंट्स डैशबोर्ड में नहीं दिख रहे हैं

1. पुष्टि करें कि कलेक्टर चल रहा है: `systemctl status agenteye-collector` (Linux) या प्रक्रिया जांचें।
2. पुष्टि करें कि `AGENTEYE_URL` `http(s)://your-server-host:8080/events` की ओर इंगित करता है (नोट: `/events` पथ)।
3. तत्काल आउटपुट देखने के लिए एक-बार फ्लश चलाएं:
   ```bash theme={null}
   agenteye-collector flush
   ```
4. जांचें कि Python SDK वास्तव में फाइलें लिख रहा है: `ls ${AGENTEYE_HOME:-~/.agenteye}/events/`
5. यदि `${AGENTEYE_HOME:-~/.agenteye}/failed/` में फाइलें मौजूद हैं, तो अपलोड विफल हो रहे हैं। कलेक्टर लॉग्स में त्रुटि जांचें, संभवतः 4xx (खराब कुंजी या URL) या नेटवर्क समस्या।

### फाइलें `$AGENTEYE_HOME/events/` में जमा हो रही हैं और अपलोड नहीं हो रही हैं

* कलेक्टर नहीं चल रहा हो सकता है। इसे शुरू करें: `agenteye-collector start`; यह स्टार्टअप पर पहले से मौजूद इवेंट्स को स्वचालित रूप से फ्लश करता है।
* कलेक्टर स्वास्थ्य जांचें: `agenteye-collector health`
* कलेक्टर चल रहा हो सकता है लेकिन सर्वर तक पहुंचने में असमर्थ है। कलेक्टर और सर्वर होस्ट के बीच फायरवाल नियम जांचें।

### `$AGENTEYE_HOME/failed/` में फाइलें

सभी पुनः प्रयास प्रयासों (डिफ़ॉल्ट: 5 प्रयास exponential backoff के साथ) के समाप्त होने के बाद फाइलें `failed/` में जाती हैं। इसका मतलब है:

* सर्वर ने 4xx त्रुटि देी (खराब कुंजी, गलत URL, या पेलोड समस्या)
* संपूर्ण पुनः प्रयास विंडो के लिए सर्वर अपहुंच्य था

अंतर्निहित समस्या को ठीक करें, फिर मैन्युअल रूप से पुनः-कतार करें:

```bash theme={null}
mv ${AGENTEYE_HOME:-~/.agenteye}/failed/*.jsonl ${AGENTEYE_HOME:-~/.agenteye}/events/
agenteye-collector flush
```

### कलेक्टर हर अपलोड पर `network error` रिपोर्ट करता है (TLS हैंडशेक विफल)

यदि `curl -k` के विरुद्ध `AGENTEYE_URL` सफल होता है लेकिन कलेक्टर बाइनरी `error sending request for url (...)` के साथ हर अपलोड विफल करता है, तो AgentEye सर्वर एक TLS प्रमाणपत्र प्रस्तुत कर रहा है जो सार्वजनिक रूप से विश्वसनीय CA द्वारा हस्ताक्षरित नहीं है।

**उत्पादन पथ** `deploy/base/certificates/domain.env` में कॉन्फ़िगर किया गया ACME ingest होस्टनाम है ([`kubernetes-deployment.md`](/hi/agenteye/kubernetes-deployment) Phase 3.1 / 4.2 देखें)। एक बार `INGEST_DOMAIN` सार्वजनिक Traefik LB में हल होने के बाद और cert-manager Let's Encrypt cert जारी कर देता है, कलेक्टर **कोई `AGENTEYE_TLS_CA` की आवश्यकता नहीं**; सिस्टम ट्रस्ट स्टोर के विरुद्ध सर्वर cert को सत्यापित करता है; यदि यह पुरानी स्व-हस्ताक्षरित तैनाती के विरुद्ध सेट था तो इसे कलेक्टर कॉन्फ़िग से साफ करें।

**लक्षण: कलेक्टर कल काम करता था, \~90-दिन के अंतराल के बाद आज विफल हो जाता है।** इसका मतलब है तैनाती अभी भी `ingest-tls` के लिए legacy `selfsigned` issuer पर है। 90-दिन का प्रमाणपत्र घुमाया गया और pinned CA फाइल पुरानी है। permanently को fix करके deployment guide के Phase 3.1 के लिए क्लस्टर को ACME issuer पर स्विच करें। short-term को अनब्लॉक करें: वर्तमान सर्वर प्रमाणपत्र को पुनः-निकालें और `AGENTEYE_TLS_CA` को अपडेट करें:

```bash theme={null}
kubectl get secret ingest-tls-cert -n agenteye \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > /etc/agenteye/server-ca.crt
```

```bash theme={null}
export AGENTEYE_TLS_CA=/etc/agenteye/server-ca.crt
agenteye-collector flush
```

`AGENTEYE_TLS_CA` एक अतिरिक्त विश्वास anchors जोड़ता है; मानक सार्वजनिक रूट्स अभी भी विश्वसनीय हैं।

### तैनाती के बाद `ingest-tls` Certificate `Ready: False` में फंस गया है

```bash theme={null}
kubectl describe certificate ingest-tls -n agenteye
```

`Events` और संदर्भित `Order` / `Challenge` देखें। सामान्य कारण:

* **DNS सार्वजनिक LB को हल नहीं कर रहा है।** HTTP-01 वेलिडेटर `INGEST_DOMAIN` तक नहीं पहुंच सकता। `dig +short INGEST_DOMAIN` के साथ सत्यापित करें; यह `traefik-public` LoadBalancer के `EXTERNAL-IP` के समान पते को हल करना चाहिए। cert-manager स्वचालित रूप से पुनः प्रयास करता है एक बार DNS प्रसारित होता है; प्रमाणपत्र को हटाने की कोई आवश्यकता नहीं है।
* **पोर्ट 80 लोड बैलेंसर / सुरक्षा समूह पर ब्लॉक किया गया है।** HTTP-01 को Let's Encrypt के सार्वजनिक वेलिडेटर्स से `:80` पहुंच योग्य होने की आवश्यकता है। यदि आपके पास अपस्ट्रीम WAF या SG `:80` को सीमित कर रहा है, तो इसे खोलें (Traefik कॉन्फ़िग HTTPS में पुनर्निर्देश करता है, लेकिन Boulder पुनर्निर्देश का पालन करता है और प्रतिक्रिया स्वीकार करता है)।
* **`dnsNames` प्रतिस्थापित नहीं।** यदि `kubectl get certificate ingest-tls -n agenteye -o jsonpath='{.spec.dnsNames}'` `INGEST_DOMAIN_PLACEHOLDER` दिखाता है, तो आपने `domain.env` स्टेप को छोड़ा; इसे `domain.env.example` से बनाएं और पुनः-लागू करें।
* **Let's Encrypt द्वारा Rate limited।** एक ही होस्टनाम के लिए बार-बार विफल आदेश डुप्लिकेट-प्रमाणपत्र या विफल-सत्यापन सीमाएं tripped करते हैं। पुनः प्रयास करने से पहले कम से कम एक घंटा प्रतीक्षा करें; सटीक rate-limit संदेश के लिए Order status जांचें।

### `dashboard-tls` Certificate `Ready: False` में फंस गया है / ब्राउज़र अभी भी चेतावनी दिखाता है

`ingest-tls` के समान निदान प्रवाह (`kubectl describe certificate dashboard-tls -n agenteye`); DNS, port-80, placeholder, और rate-limit कारण सभी लागू होते हैं, साथ ही दो डैशबोर्ड-विशिष्ट भी:

* **`DASHBOARD_DOMAIN` गलत LoadBalancer को हल करता है।** यह सार्वजनिक ingest के बजाय *डैशबोर्ड* Traefik LB की ओर इंगित करना चाहिए। होस्टनाम को `dig +short` करें और डैशबोर्ड LB पते के विरुद्ध तुलना करें।
* **डैशबोर्ड Traefik इंस्टेंस चुनौती को परोस नहीं सकता है।** इसे bundled डैशबोर्ड values फाइल के साथ स्थापित किया जाना चाहिए, जो cert-manager के HTTP-01 solver के लिए scoped Ingress प्रदाता को सक्षम बनाता है। इसके बिना solver अप्राप्य है और Order हमेशा के लिए `pending` रहता है। प्रदान किए गए values के साथ इंस्टेंस को अपग्रेड करें; pending challenge फिर अपने आप पूरा हो जाता है।
* **LoadBalancer IP-प्रतिबंधित था।** स्रोत रेंज पोर्ट 80 पर भी लागू होती हैं, जो Let's Encrypt के वेलिडेटर्स को ब्लॉक करता है — पहली जारी और हर \~75-दिन की नवीकरण दोनों। LB को खोलें, या इसे लॉक करने से पहले support के साथ DNS-01 solver का समन्वय करें।

जारी करना विफल होने के दौरान, डैशबोर्ड अपना पिछला प्रमाणपत्र (या ताजी install पर ingress डिफ़ॉल्ट) परोस रहा है — पहुंच ब्राउज़र चेतावनी द्वारा कम हो गया है, कभी नीचे नहीं।

### CLI अभी भी TLS सत्यापन को छोड़ता है डैशबोर्ड को विश्वस्त प्रमाणपत्र मिलने के बाद

`--insecure` को `cli.json` पर login पर persist किया जाता है। एक बार डैशबोर्ड सार्वजनिक रूप से विश्वसनीय प्रमाणपत्र परोस रहा हो, `agenteye --base-url https://<your-dashboard-domain> --secure login` के साथ फिर से लॉगिन करें; सत्यापन वापस बचाया जाता है और startup चेतावनी गायब हो जाती है।

***

## डैशबोर्ड समस्याएं

### `ADMIN_EMAIL` उपयोगकर्ता को अक्षम या संपादित नहीं कर सकते

डिज़ाइन के अनुसार। `ADMIN_EMAIL` से मेल खाने वाला उपयोगकर्ता हर सर्वर स्टार्टअप पर protected के रूप में चिह्नित किया जाता है: डैशबोर्ड उस पंक्ति के लिए Disable बटन छुपाता है, और API इसके विरुद्ध `DELETE /users/:id` और `PUT /users/:id` को `403 Forbidden` के साथ अस्वीकार करता है। एक डेटाबेस ट्रिगर भी प्रत्यक्ष `UPDATE` स्टेटमेंट को अस्वीकार करता है जो protected पंक्ति को अक्षम करेंगे।

बूटस्ट्रैप admin को rotate करने के लिए, अपने environment में `ADMIN_EMAIL` बदलें और सर्वर को पुनरारंभ करें। नया ईमेल protected के रूप में upserted है। पिछला admin protected ध्वज को retain करता है जब तक डेटाबेस में साफ नहीं किया जाता (आमतौर पर ठीक है, क्योंकि पिछला ईमेल तब तक एक valid admin है जब तक आप स्पष्ट रूप से उन्हें नहीं हटाते)।

### डैशबोर्ड कोई इवेंट्स नहीं दिखाता है

1. डैशबोर्ड के environment वेरिएबल्स (`AGENTEYE_SERVER_URL`, `AGENTEYE_API_KEY`) में सर्वर URL और API कुंजी सही हैं यह पुष्टि करें।
2. डैशबोर्ड API कुंजी को `events:read` अनुमति की आवश्यकता है।
3. इवेंट्स वास्तव में ingested हैं यह पुष्टि करें: `curl http://your-server:8080/events -H "Authorization: Bearer $ADMIN_KEY"`

### `/errors` खाली है लेकिन `/events` लाल पंक्तियां दिखाता है

नए SDK संस्करण `agent_end` / `tool_result` / `hook_completed` इवेंट्स के रूप में failures को dedicated `event_type: "error"` पंक्ति के बजाय पेलोड में `outcome: "error"` के साथ उत्सर्जित करते हैं। `/errors` पृष्ठ अब दोनों को जोड़ता है: कोई भी पंक्ति जो `/events` स्ट्रीम लाल रंग में पेंट करता है (explicit `event_type='error'`, पेलोड `outcome`/`status` विफलता सेट में, `is_error: true`, या truthy `error` फील्ड) `/errors` पर दिखाई देता है। यदि आप पहले "/events" पर red पंक्तियों के visible होने के दौरान "no errors in this window" देखते थे, तो डैशबोर्ड + सर्वर को एक साथ अपग्रेड करें (broadened filter `errored=true` on `GET /events` है) और दोनों views सहमत होंगे।

### `/models`, `/tools`, या `/hooks` wide समय रेंज पर धीमा या लोड करने में विफल है

**लक्षण:** एक बड़ी events तालिका पर (लाखों पंक्तियां), `/models`, `/tools`, या `/hooks` को खोलना — या समय रेंज को `7d`, `30d`, या `all` तक चौड़ा करना — चार्ट स्पिन करते हैं और फिर लोड त्रुटि दिखाते हैं। सर्वर `latency_aggregate` अनुरोध के लिए ClickHouse `MEMORY_LIMIT_EXCEEDED` (Code 241) या query timeout को लॉग करता है।

**कारण:** पुरानी builds ने इन पृष्ठों की latency और distribution rollups को एक query के साथ गणना की जो पूरे raw event `payload` को पढ़ता है और request/response events को एक in-memory sort-and-join के साथ जोड़ता है। Peak query memory इसलिए विंडो के आकार के साथ बढ़ता है, इसलिए एक busy tenant पर एक wide रेंज ClickHouse के per-query memory ceiling को exceed कर सकता है।

**Fix:** इस fix को शामिल करने वाली build में अपग्रेड करें। Rollup अब केवल compact promoted columns को पढ़ता है और events को streaming aggregation के साथ जोड़ता है, इसलिए peak memory अब raw payload के आकार के साथ स्केल नहीं करता है — wide windows memory ceiling के भीतर अच्छी तरह रहते हैं और fraction of time में return होते हैं। सुधार पूरी तरह से query-side है: यह अगले पृष्ठ लोड पर सभी मौजूदा data पर लागू होता है, कोई re-ingest या backfill के बिना।

### डैशबोर्ड लोड करने में विफल / blank पृष्ठ

डैशबोर्ड कंटेनर लॉग्स जांचें:

```bash theme={null}
docker logs agenteye-dashboard
```

सबसे सामान्य कारण `AGENTEYE_SERVER_URL` या `AGENTEYE_API_KEY` missing है या unreachable सर्वर की ओर इंगित करता है।

### डैशबोर्ड विश्लेषण / टेलीमेट्री

डैशबोर्ड डिफ़ॉल्ट रूप से anonymous product-usage analytics को PostHog को भेजता है, डैशबोर्ड के अपने `/ingest` पथ के माध्यम से routed (a reverse proxy to `https://us.i.posthog.com`)। उन्हें first-party के माध्यम से भेजने का मतलब ब्राउज़र ad-blockers उन्हें drop नहीं करते। यह डैशबोर्ड की मुख्य कार्यक्षमता से independent है:

* **डैशबोर्ड कंटेनर** (ब्राउज़र नहीं) वही है जो PostHog तक पहुंचता है। यदि इसकी आउटबाउंड access `https://us.i.posthog.com` को ब्लॉक किया जाता है, तो टेलीमेट्री silently no-ops; डैशबोर्ड सामान्य रूप से काम करता है और कोई त्रुटियां users को surfaced नहीं होती हैं।
* कोई agent, session, या event data कभी included नहीं है, केवल dashboard UI usage।
* टेलीमेट्री को पूरी तरह से अक्षम करने के लिए, डैशबोर्ड कंटेनर पर `AE_ANALYTICS_DISABLED=1` सेट करें और पुनरारंभ करें। तैनाती guide में [Telemetry & privacy](/hi/agenteye/deployment#telemetry--privacy) देखें।

### CLI विश्लेषण / टेलीमेट्री

`agenteye` CLI डिफ़ॉल्ट रूप से anonymous usage analytics को PostHog को भेजता है: कौन सी commands चलती हैं, success/exit status, और duration। यह CLI की कार्यक्षमता से independent है:

* **CLI चलाने वाली machine** `https://us.i.posthog.com` सीधे तक पहुंचता है। यदि इसकी आउटबाउंड access ब्लॉक किया जाता है, तो टेलीमेट्री silently no-ops (sending time-bounded है, इसलिए यह कभी command को delay नहीं करता) और CLI सामान्य रूप से काम करता है।
* कोई agent, session, या event data कभी included नहीं है: command **arguments और flag values** (dashboard URL, token, email, session ids, query filters) कभी नहीं भेजे जाते हैं।
* इसे अक्षम करने के लिए, CLI के environment में `AGENTEYE_ANALYTICS_DISABLED=1` (या cross-tool `DO_NOT_TRACK=1`) सेट करें। CLI guide में [Telemetry & privacy](/hi/agenteye/cli#telemetry--privacy) देखें।

***

## एआई असिस्टेंट समस्याएं

पूर्ण setup के लिए [enterprise-docs/assistant.md](/hi/agenteye/assistant) देखें।

### असिस्टेंट बुलबुला नहीं दिखाई देता है

बुलबुला hidden है जब तक **सभी** ये hold नहीं करते:

* Signed-in user के पास `agent:use` अनुमति है।
* `AGENTEYE_AGENT_URL` डैशबोर्ड पर सेट है और `agent` सेवा पहुंच योग्य है।
* एक LLM endpoint `agent` सेवा पर कॉन्फ़िगर किया गया है (`ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` के माध्यम से एक gateway, या Bedrock/Vertex)। कोई भी सेट नहीं होने पर, agent "not configured" रिपोर्ट करता है और बुलबुला hidden रहता है।

डैशबोर्ड होस्ट से agent के स्वास्थ्य की जांच करें: `curl http://agent:9100/health` को `{"status":"ok","llm_configured":true,...}` return करना चाहिए।

### असिस्टेंट कहता है कि यह कुछ नहीं पढ़ सकता

Tools प्रति-user gated हैं। यदि user के पास `evaluations:read` (या `events:read`, `dashboards:read`) नहीं है, तो मिलान tools offered नहीं हैं और असिस्टेंट कहेगा कि यह वह data नहीं पढ़ सकता। प्रासंगिक read अनुमति दें।

### भेजते समय "assistant not configured" (HTTP 503)

`agent` कंटेनर के पास कोई LLM endpoint कॉन्फ़िगर नहीं है, या डैशबोर्ड का `AGENTEYE_AGENT_TOKEN` agent के से मेल नहीं खाता। दोनों सेट करें और पुनरारंभ करें।

### `agent` कंटेनर लोड के तहत restarts / OOMs

प्रत्येक बातचीत एक short-lived child process spawn करता है। सुनिश्चित करें कि कंटेनर एक init process के साथ चलता है (image `tini` का उपयोग करता है; Compose में `init: true` सेट करें) और इसे adequate memory limits दें। यदि आवश्यक हो तो `AGENTEYE_AGENT_MAX_STEPS` को कम करें।

***

## CLI समस्याएं

### `agenteye` `ModuleNotFoundError: No module named 'click'` के साथ शुरू करने में विफल

Version **0.1.6** पर `agenteye` CLI का ताजा install:

```
ModuleNotFoundError: No module named 'click'
```

के साथ crash हो सकता है।

0.1.6 `click` को `typer` द्वारा indirectly स्थापित किए जाने पर निर्भर था; वर्तमान `typer` releases अब इसे pull नहीं करते हैं, इसलिए एक clean environment में पैकेज missing हो सकता है। **0.1.7 या नए में अपग्रेड करें**, जो `click` पर directly निर्भर है:

```bash theme={null}
pipx upgrade agenteye      # यदि pipx के साथ स्थापित (या: pipx install --force agenteye)
uv tool upgrade agenteye   # यदि uv के साथ स्थापित
pip install --upgrade agenteye
```

Install guidance के लिए [enterprise-docs/cli.md](/hi/agenteye/cli) देखें।

***

## Python SDK समस्याएं

### `$AGENTEYE_HOME/events/` में कोई फाइलें नहीं दिख रहीं

SDK events को buffer करता है और डिफ़ॉल्ट रूप से हर 500 ms को flush करता है। यदि आपकी प्रक्रिया flush से पहले exits करती है, तो events खो सकते हैं। short-lived scripts में तेजी से flushing के लिए `agenteye.configure(flush_interval=0.1)` को कॉल करें, या सुनिश्चित करें कि आपकी प्रक्रिया एक flush cycle के लिए काफी time चलती है।

यदि `AGENTEYE_HOME` सेट है, तो सत्यापित करें कि SDK `$AGENTEYE_HOME/events/` में लिख रहा है न कि `~/.agenteye/events/` (requires SDK ≥ 0.0.1b5)।

### `ValueError: Reserved field names cannot be used as custom fields`

नाम `timestamp`, `type`, और `environment` reserved हैं और custom fields के रूप में उपयोग नहीं किए जा सकते। इनमें से कोई भी पास करना raise करता है:

```
ValueError: Reserved field names cannot be used as custom fields: [...]
```

offensive custom field को rename करें। नोट करें कि `session_id` और `agent_id` event call के explicit parameters हैं, custom fields नहीं; किसी को फिर से custom field के रूप में passing करना `TypeError` raise करता है।

***

## Health Monitoring समस्याएं

### Slack में कोई alerts नहीं आ रहे (Robusta)

Robusta health alerting **opt-in** है; जब तक स्थापित और Slack channel की ओर इंगित नहीं किया जाता है तब तक यह कुछ नहीं भेजता। release और इसके sink को सत्यापित करें:

```bash theme={null}
kubectl get pods -n robusta          # robusta-runner + robusta-forwarder Running होना चाहिए
kubectl logs -n robusta -l app=robusta-runner --tail=50
```

सामान्य कारण: Slack `api_key` / `slack_channel` सेट नहीं थे (या token को revoked किया गया); `api_key` Robusta cloud-relay token है (`robusta integrations slack`) लेकिन bundled `disableCloudRouting: true` को self-hosted Slack **bot token** (`xoxb-…`) की आवश्यकता है, या `disableCloudRouting: false` सेट करें; sink `scope` उस namespace को exclude करता है जहां आपके pods चलते हैं (bundled values scope to `agenteye`); या कोई failure अभी नहीं हुआ है। एक pod को नीचे ले जाकर एक test alert को force करें:

```bash theme={null}
kubectl -n agenteye delete pod -l app=clickhouse   # यह recreate होगा
```

Install और configuration के लिए [enterprise-docs/health-monitoring.md](/hi/agenteye/health-monitoring#2-pod-failure-alerting-with-robusta-opt-in) देखें।

### सर्वर लगातार `NotReady` फ्लैप कर रहा है

Readiness probe `/ready` को hit करता है, जो Postgres या ClickHouse unreachable होने पर fail होता है। यदि सर्वर `NotReady` में और बाहर चक्र कर रहा है, तो dependency intermittently unavailable है; ClickHouse और Postgres pods को जांचें और सर्वर के `CLICKHOUSE_URL` / `DATABASE_URL` को जांचें। पुष्टि करें कि `/ready` क्या रिपोर्ट करता है:

```bash theme={null}
kubectl -n agenteye exec deploy/server -- sh -c 'curl -s localhost:8080/ready'
```

यह probe deliberately tolerant है (एक generous failure threshold), इसलिए sustained flapping एक real dependency समस्या को indicate करता है rather than an over-aggressive probe। Liveness `/health` पर रहता है, इसलिए flapping readiness pod को **नहीं** restart करेगा।

## Certificate Monitoring समस्याएं

### CronJob Slack notifications नहीं भेज रहा है

`cert-renewal-check` CronJob को एक Secret में stored Slack webhook URL की आवश्यकता है। सत्यापित करें यह मौजूद है:

```bash theme={null}
kubectl get secret cert-renewal-notify-config -n agenteye
```

यदि missing है, इसे बनाएं:

```bash theme={null}
kubectl create secret generic cert-renewal-notify-config \
  --namespace agenteye \
  --from-literal=SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
```

Secret के बिना, CronJob अभी भी चलता है और results को stdout में लॉग करता है। Logs को check करें with:

```bash theme={null}
kubectl logs -n agenteye -l job-name --tail=50
```

### Client certificate notification प्राप्त होने से पहले expire हुआ

CronJob हर 12 घंटे चलता है। यदि यह चल नहीं रहा है, तो इसकी status को check करें:

```bash theme={null}
kubectl get cronjob cert-renewal-check -n agenteye
```

एक manual check trigger करें:

```bash theme={null}
kubectl create job --from=cronjob/cert-renewal-check manual-cert-check -n agenteye
kubectl logs -n agenteye -l job-name=manual-cert-check
```

Expired certificate को तुरंत re-issue करने के लिए:

```bash theme={null}
cd base/certificates/client-certs
./issue-client-cert.sh <cluster-name>
```

फिर regenerated `collector-mtls-secret.yaml` को cluster(s) में apply करें जहां आपके collectors चलते हैं और उन्हें restart करें:

```bash theme={null}
kubectl apply -f collector-mtls-secret.yaml -n <collector-namespace>
```

***

## Backup समस्याएं

### `agenteye-backup` "No space left on device" के साथ विफल

`agenteye-backup` CronJob Postgres + ClickHouse को एक `backup-tmp` `emptyDir` scratch volume (default `30Gi`) में dumps करता है, फिर **streams** `tar` archive सीधे S3 को — compressed archive कभी scratch में वापस written नहीं है, इसलिए scratch को केवल *raw dumps* को hold करना है, न dumps + a second on-disk archive copy को। एक pod evicted / `No space left on device` इसलिए मतलब है कि **raw dumps** scratch size को exceed करते हैं (ClickHouse `events` dump dominates और time के साथ बढ़ता है)। Failed job के logs को check करें:

```bash theme={null}
kubectl logs -n agenteye -l job-name=<failed agenteye-backup job>
```

Fix: आपके overlay में, CronJob के `backup-tmp` `emptyDir` `sizeLimit` को अपने raw dump total से ऊपर raise करें, और सुनिश्चित करें कि node की ephemeral storage वास्तव में इसे hold कर सकता है (`sizeLimit` एक cap है, न कि एक reservation)। यदि dumps एक single node's disk को outgrow करते हैं, तो `emptyDir` को `backup-tmp` के लिए PVC (EBS/PD) से replace करें, या source पर dumps को compress करें।

> पुरानी releases को `.tar.gz` को dumps के समान `20Gi` scratch में लिखता था, इसलिए `dumps + archive` इसे overflow करता था और pod को **before** the upload ran से evict किया जाता था — जो S3 failure की तरह लगता है लेकिन वास्तव में disk है। Streaming the upload that doubling को remove करता है।

### `agenteye-backup` `curl` install करने में विफल

Job `postgres:16` image पर चलता है और ClickHouse HTTP dump के लिए startup पर `curl` को install करता है। कोई cluster egress के साथ Debian package mirrors के लिए, `apt-get` step fail होता है। या तो backup pod से उस egress को allow करें, या एक mirrored/custom backup image में `curl` को bake करें और अपने overlay में इसे reference करें।

### `agenteye-backup` चलता है लेकिन कुछ भी object storage में lands नहीं करता है

Base एक real `BACKUP_BUCKET` (`ts-prod-agenteye/backups`) और `agenteye-backup` ServiceAccount ship करता है। Job **streams** archive को S3 (`tar cz … | aws s3 cp - s3://…`)। यदि backup pod के पास bucket के लिए write access नहीं है, तो upload errors — और क्योंकि script `set -euo pipefail` के तहत चलता है, उस pipe में कहीं भी failure **पूरे** job को `upload` step में fail करता है rather than silently no-op'ing (pod का EXIT trap `backup FAILED during step: upload` को logs करता है)। यह भी step है जो आप एक scratch-space eviction को fix करने के बाद reach करते हैं, इसलिए यदि backups पहले archive step पर evicted थे, तो सत्यापित करें कि upload अब lands करता है। Failed job के logs में S3 access error को grep करें:

```bash theme={null}
kubectl logs -n agenteye -l job-name=<failed agenteye-backup job> | grep -iE 's3|upload|denied'
```

Fix: अपने overlay में `BACKUP_BUCKET` को एक bucket पर सेट करें जो आप own करते हैं और write access के साथ existing `agenteye-backup` ServiceAccount को annotate करें (IRSA / Workload Identity / Pod Identity)। [enterprise-docs/kubernetes-deployment.md](/hi/agenteye/kubernetes-deployment) के **Backups** section को देखें।

***

## ClickHouse-backed evaluations / sessions / queries

### अपग्रेड के बाद `/queries` पृष्ठ sidebar खाली है

तीन tables (`events`, `evaluations`, `agent_sessions`) expected हैं। यदि SchemaBrowser sidebar upgrade के बाद खाली है, तो सर्वर startup पर ClickHouse DDL apply करने में विफल हुआ। `failed to apply CH DDL statement` के लिए सर्वर logs को check करें:

```bash theme={null}
kubectl logs -n agenteye deploy/server | grep -E 'clickhouse|CH DDL'
```

सबसे सामान्य कारण ClickHouse unreachable है जबकि migrations चलते हैं। सर्वर CH तक reach नहीं कर सकता तो start करने से refuse करता है, इसलिए एक stuck pod में आमतौर पर `CrashLoopBackOff` होता है rather than silently broken queries page, लेकिन एक partial DDL apply (एक statement OK, अगले 5xx) schema को half-baked छोड़ देता है। CH को verify reachable करने के बाद server pod को restart करें:

```bash theme={null}
kubectl rollout restart deploy/server -n agenteye
```

### नए evaluations `/sessions` या `/queries` में नहीं दिख रहे हैं

अपग्रेड के बाद, नए evaluations ClickHouse को लिखे जाते हैं, Postgres को नहीं, और `/sessions` (`evaluations:read` पर gated) और `/queries` में surface होते हैं। यदि वे नहीं दिखते हैं:

1. पुष्टि करें कि evaluator pipeline enabled है (`AGENTEYE_AGENT_URL` सर्वर पर सेट) और terminal outcomes produce कर रहा है; `evaluation_finalized` log lines के लिए check करें।
2. पुष्टि करें कि CH सर्वर से reachable है: `kubectl exec -n agenteye deploy/server -- curl -fsS http://clickhouse:8123/ping`।
3. CH table को spot-check करें: `kubectl exec -n agenteye clickhouse-0 -- clickhouse-client -q 'SELECT count() FROM agenteye.evaluations'`।

### Queries लोड के तहत "Memory limit exceeded" के साथ विफल, या ClickHouse `OOMKilled` है

**लक्षण:** भारी dashboard/query लोड के तहत, analytical pages (the events stream, `/sessions`, models/latency view, SQL editor) fail होने लगते हैं या timeout करते हैं; सर्वर संक्षिप्त रूप से flaps `NotReady`; और ClickHouse pod restart count बढ़ता दिखाता है। यह लगभग हमेशा **memory** है, न कि CPU या disk।

**पुष्टि करें यह memory है** (न कि throughput समस्या जो replication fix करेगा):

1. Pod को out-of-memory kills के लिए check करें:
   ```bash theme={null}
   kubectl -n agenteye describe pod clickhouse-0 | grep -iE 'Restart Count|Last State|Reason|OOMKilled'
   ```
   `Reason: OOMKilled` / `Exit Code: 137` एक climbing restart count के साथ tell है।

2. ClickHouse से पूछें यह क्या reject कर रहा है:
   ```bash theme={null}
   kubectl -n agenteye exec clickhouse-0 -- clickhouse-client -q \
     "SELECT name, value FROM system.errors WHERE value>0 ORDER BY value DESC"
   ```
   एक large \`MEMORY