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

# Sorun Giderme

> Yaygın hata mesajları ve çözümleri — upload errors, model run errors, budget errors, report errors.

# Sorun Giderme

Yaygın hata mesajları + çözüm rehberi. Sorununuzu bulamadıysanız `destek@mmmytics.com`.

## Upload Errors

### "PII detected — file rejected"

**Sebep:** CSV'nizde TCKN, isim, email, telefon veya adres içeren sütun var.

**Çözüm:**

1. CSV'yi Excel'de aç
2. PII içeren sütunları sil (genelde first\_name, last\_name, email, phone, address, tckn)
3. Sadece **agregat haftalık** veri bırak (week, kpi, channel\_spends)
4. CSV UTF-8 olarak save → tekrar yükle

**Neden?** KVKK Madde 5/2-c (rıza olmadan kişisel veri işleme yasak). MMM agregat veri ile çalışır, kişisel veriye ihtiyaç duymaz.

### "Insufficient weeks (minimum 26 required)"

**Sebep:** CSV'nizde 26 haftadan az veri var.

**Çözüm:**

* Daha fazla geçmiş veri ekleyin (veri ambar, Google Sheets, vs.)
* Veya günlük veri varsa haftalık aggregate edin (Pazartesi başlangıç)
* Minimum 6 ay (26 hafta) gerekli — daha az veri MMM güvenilir değil

### "Encoding error — UTF-8 expected"

**Sebep:** CSV Latin-1 / Windows-1254 encoding'de.

**Çözüm:**

* Excel: "Save As" → "CSV UTF-8 (delimited)" formatını seç
* Numbers (Mac): "Export" → CSV → Encoding: Unicode (UTF-8)
* Notepad (Windows): "Save As" → Encoding: UTF-8 (büyük U-T-F)

### "Date format error — ISO 8601 (YYYY-MM-DD) expected"

**Sebep:** `week` sütunu Türkçe format (DD.MM.YYYY) veya US format (MM/DD/YYYY).

**Çözüm:**

* Excel'de week sütunu → Format Cells → Custom: `yyyy-mm-dd`
* Tüm satırlar Pazartesi tarihi olmalı (haftanın başı)
* Örnek: `2025-01-06` (Pazartesi), `2025-01-13` (sonraki Pazartesi)

### "Channel sütun adı tanınmadı"

**Sebep:** Kanal sütunu format yanlış (örn: `TV harcama`, `Television`, `tv_amount`).

**Çözüm:**

* Standart format: `<channel>_spend` (lowercase, underscore)
* Örnekler: `tv_spend`, `youtube_spend`, `google_ads_spend`, `meta_ads_spend`, `ooh_spend`
* L2 Model Studio'da custom kanal adı tanımlanırsa o eşleşmeli

### "Aynı hafta için duplicate satır"

**Sebep:** CSV'de aynı `week` değeri birden fazla satırda.

**Çözüm:**

* Excel'de `week` sütunu unique olmalı
* Aynı hafta varsa pivot ile aggregate (sum kanalı, sum KPI)

***

## Model Run Errors

### "R-hat divergence — model failed to converge"

**Sebep:** MCMC zincirleri yakınsamadı, R-hat > 1.10.

**Çözüm öncelik sırası:**

1. **DQS upgrade**: L1 Data Hub → DQS panel önerilerini uygula → re-upload
2. **Adstock/saturation defaults**: L2 → "Restore defaults" butonu
3. **Bağlam değişken ekle**: FX, CPI, Ramadan tickli mi kontrol et
4. **Outlier hafta exclude**: L1 → DQS panel'da outlier flag'lı haftaları manuel düzelt
5. **Re-run** → tekrar fail ediyorsa `destek@mmmytics.com`

### "MAPE > 30% — model accuracy low"

**Sebep:** Modelin tahmini gerçeklikle uyumsuz, eksik faktör var.

**Çözüm:**

1. **Eksik majör kanal**: Affiliate, Influencer, Email gibi unutulan kanalı CSV'ye ekle
2. **Yapısal değişiklik**: rebrand, fiyat şoku, lokasyon ekleme — bu olayları bağlam değişkeni olarak ekle
3. **Outlier dönem**: COVID benzeri olağandışı dönemi exclude et veya flag ekle
4. **Daha fazla veri**: 26 → 52 hafta'a çıkar

### "GPU timeout — run exceeded 10 minutes"

**Sebep:** Model çok karmaşık (15+ kanal × 200+ hafta × 10+ bağlam).

**Çözüm:**

* L2 → blueprint sadeleştir:
  * Kanal sayısını 6-8'e indir (alt-kanalları aggregate et)
  * Bağlam değişken sayısını 5-7'ye indir
* Veya hafta sayısını 104'e (son 2 yıl) sınırla
* Re-run

### "OOM (Out of Memory)"

**Sebep:** GPU bellek yetersiz (200+ hafta × 15+ kanal kombinasyonu).

**Çözüm:**

* Veriyi 104 haftaya kısalt (son 2 yıl)
* Kanal sayısını 8'e indir
* Eğer hala OOM → `destek@mmmytics.com` (GPU upgrade requesti)

### "Run hala 'Queued' 30+ dakikadır"

**Sebep:** GPU quota dolmuş veya sistem bakımda.

**Çözüm:**

1. [status.mmmytics.com](https://status.mmmytics.com) kontrol et (engine maintenance var mı?)
2. Aylık GPU quota kontrolü (`/dashboard/engine` üst köşesi)
3. Quota dolmuşsa `destek@mmmytics.com` (admin onayı için)

***

## Budget Optimizer Errors

### "Cannot create scenario — model run not completed"

**Sebep:** L5 Budget Optimizer, completed model run gerektirir.

**Çözüm:**

* L3 Engine'de en az 1 başarılı run yap
* Run completed status almalı (R-hat \< 1.05, MAPE \< 30%)

### "422 — scenario constraints invalid"

**Sebep:** Channel mix override constraints geçersiz (örn: lock 2M TL ama toplam 1M TL).

**Çözüm:**

* Lock değerleri toplamı toplam bütçeyi aşmamalı
* Min/max sınırları realistic olmalı (negatif veya 0 yasak)

### "Compare view boş gözüküyor"

**Sebep:** Compare için 2+ scenario gerekli.

**Çözüm:**

* "Senaryo Oluştur" ile en az 2 senaryo oluştur (örn: Baseline + Optimized)
* Sonra Compare butonu çalışır

### "Multi-run baseline mismatch warning"

**Sebep:** Compare'da farklı **model run**'lardan senaryolar var.

**Çözüm:**

* Aynı run'dan senaryolar üret (önerilen)
* Veya warning'i kabul et — ama doğrudan karşılaştırma yanıltıcı olabilir

***

## Report Errors

### "PDF generation timeout"

**Sebep:** PDF render 30 saniyeyi aştı (çok büyük dataset veya kompleks senaryo).

**Çözüm:**

1. Beklemeden refresh sayfa, tekrar dene
2. Hala timeout → `destek@mmmytics.com` (P2 ticket — backend log incelenir)

### "Report download link expired"

**Sebep:** Signed URL 1 saat süreli (Supabase Storage).

**Çözüm:**

* L7 Reports → "Yeniden Generate" butonu
* Yeni signed URL oluşur

### "Scenario fallback message in report"

**Sebep:** Henüz L5'te senaryo oluşturmamışsınız.

**Çözüm:**

* L5 Budget Optimizer → en az 1 senaryo oluştur
* Sonra L7 Reports'ta scenario seç → re-generate

***

## Authentication / Sign-in

### "Invitation link expired"

**Sebep:** Clerk davet linki 24 saat geçerli.

**Çözüm:** `destek@mmmytics.com` → admin yeni davet gönderir.

### "Forgot password"

**Sebep:** Şifrenizi unuttunuz.

**Çözüm:** `/sign-in` → "Forgot password?" → email'inize sıfırlama linki.

### "2FA code rejected"

**Sebep:** Authenticator app'in saati senkron değil.

**Çözüm:**

* Telefon settings → Date & Time → Auto sync on
* Authenticator app'i yeniden aç, kodu tekrar gir

***

## API Errors

### 401 Unauthorized

**Sebep:** JWT token expired veya invalid.

**Çözüm:**

* Yeni JWT al: Clerk session → `getToken()`
* Bearer header doğru mu? `Authorization: Bearer <jwt>`

### 403 Forbidden

**Sebep:** Brand erişiminiz yok (cross-brand RBAC isolation).

**Çözüm:**

* Sadece atandığınız brand'lere erişebilirsiniz
* Yanlış brand\_id mi gönderiyorsunuz?
* `destek@mmmytics.com` (admin role check)

### 429 Rate Limited

**Sebep:** API rate limit aşıldı (default 100 req/min).

**Çözüm:**

* Retry-After header'ı bekleyin (genelde 60 sn)
* İleri seviye usage için yüksek rate limit `destek@mmmytics.com`

### 500 Internal Server Error

**Sebep:** Backend bug veya kapasite sorunu.

**Çözüm:**

1. Tekrar dene (intermittent error)
2. Sentry otomatik issue açar — backend ekip incelenir
3. Hala devam ediyorsa `destek@mmmytics.com` (timestamp + endpoint paylaş)

***

## Phase 24 — Settings & Admin Errors

### `BENCHMARK_OVERRIDE_ORDER_INVALID`

**Sebep:** Per-brand benchmark override eşik değerleri yanlış sırada — `low_warn ≥ low_info` veya `high_info ≥ high_warn`.

**Çözüm:**

* Değerleri **artan sırada** girin: `low_warn < low_info < high_info < high_warn`
* Örnek: CPC için `low_warn = 0.5`, `low_info = 1.0`, `high_info = 3.0`, `high_warn = 5.0`
* Dialog form validation hatayı submit öncesi gösterir; sıralamayı düzeltip tekrar deneyin

**Yetki:** `CEO` veya `CMO` rolü gereklidir. Detay: [Per-Brand Benchmark Override](/settings/benchmark-overrides)

### `CACHE_INVALIDATE_SCOPE_INVALID`

**Sebep:** Composer LLM cache invalidation scope + parametre uyumsuzluğu:

* `scope=locale` ama `locales` boş array
* `scope=variant` ama `variant_ids` boş array
* `scope=run_id` ama `run_id` UUID formatı geçersiz

**Çözüm:**

* `scope=all` → ek parametre gerekmez
* `scope=locale` → `locales: ["tr", "en"]` formatında dolu liste
* `scope=variant` → `variant_ids: ["v1.0", "v1.1"]` formatında dolu liste
* `scope=run_id` → geçerli UUID v4 (örn: `24774cd8-...`)

**Yetki:** `platform_admin` rolü gereklidir. Detay: [Composer LLM Cache Invalidation](/admin/cache-invalidation)

### `BRAND_ACCESS_FORBIDDEN_403`

**Sebep:** `Agency` rolündeki kullanıcı `assigned_brand_ids` dışında bir brand'e erişmeye çalıştı (cross-org isolation, PostgreSQL RLS).

**Çözüm:**

1. **Platform Admin'den assignment iste** — `destek@mmmytics.com` üzerinden hangi brand'lere erişim gerektiğini bildirin
2. Admin `users.assigned_brand_ids` array'ine brand UUID ekler
3. Logout + login (Clerk JWT yenilenir) → erişim aktif olur

**Not:** `CEO`/`CMO` rolü org içindeki tüm brand'lere erişebilir; bu hata sadece `Agency` rolünde görülür.

***

## Hala Çözüm Bulamadınız mı?

<CardGroup cols={2}>
  <Card title="Destek Email" icon="envelope" href="mailto:destek@mmmytics.com">
    `destek@mmmytics.com` — P0 4h, P1 24h, P2 5 iş günü
  </Card>

  <Card title="Sistem Durumu" icon="signal" href="https://status.mmmytics.com">
    Önce kontrol edin — sistem çapraz mu?
  </Card>
</CardGroup>

**Hata raporlarken belirtin:**

* Hata mesajı (tam metin)
* URL veya endpoint
* Timestamp (UTC)
* Sentry event ID (varsa)
* Reproduce adımları