# Troubleshooting Common issues and their fixes. ## No Hints / Options Are Generated 1. **Check your API key**: Go to **Config → AI Providers**, select your provider, paste the key, and click **Test**. A ❌ means the key or endpoint is wrong. 2. **Check the master switches**: In **General**, ensure **Generate Hints** and **Generate Options (MCQ)** are enabled. Turning both off disables all generation. 3. **Check auto-show settings**: If data exists but isn't visible, the hints/options may be collapsed. Verify **Auto Show Hints** / **Auto Show Options** (front and answer side) in the General tab. 4. **Check the model**: Some models may refuse or return empty output. Try **Fetch** to update the model list, or switch models. 5. **View the logs**: Open the **Logs** tab and look for errors. Enable **Debug logging** for detailed request/response info. ## Model Test Says "Returned No Parseable Hints/Options" - **Update to v7.0.4+** first: gateways like the Cline BYOK API (`api.cline.bot`) wrap completions in a top-level `data` envelope, and reasoning models often return the JSON in `message.reasoning` / `reasoning_details` instead of `content`. Older builds read only `message.content` and could not see valid output. - If it still fails, enable **Debug logging** in the **Logs** tab and check the `FULL RESPONSE` line: if the response contains neither a JSON object in `content` nor in the reasoning fields, the model simply did not produce usable output — try another model or adjust the prompt. - Gateways with **no model-list endpoint** (e.g. Cline's) always fail **Fetch Models** — that is expected; add models manually via **Fallbacks → Add Model...**. ## Garbled / Corrupted Generated Text - If generated hints/options come back as mixed-script garbage (for example Malayalam interleaved with CJK or Devanagari characters), the on-wire text contains `U+FFFD` replacement characters — a sign of a **broken model or tokenizer** on the provider side, not an add-on encoding bug. The add-on sends and receives clean UTF-8. - AI-Hints now detects any generated text containing `U+FFFD` and **discards that generation**, logging a warning (`AI-Hints: discarding corrupt model output containing U+FFFD replacement characters...`) and falling back to the next model in the priority list. A corrupt card therefore fails over gracefully instead of committing garbage hints to your notes. - If you see this repeatedly for a specific model, prefer another model — the offending one is being rejected as unusable. ## The Generate Button Does Nothing / Is Disabled - If the button is **disabled**, both **Generate Hints** and **Generate Options (MCQ)** are turned off. Re-enable at least one in the General tab. ## Rate Limits / API Errors AI-Hints automatically falls back to the next provider/model in your priority list. If you're hitting limits: - Add **more providers** with keys, or add **multiple keys per provider** (rotation). - Increase the **Default Failure Lockout** or adjust timeouts in the Advanced tab. - Models that fail repeatedly are temporarily blacklisted; use **Clear All Cooldowns** in Advanced to reset. ## My Manual Edits to Hints / Options Keep Getting Overwritten - AI-Hints uses an immutable snapshot of the cloze answer to detect stale data, so genuine manual edits are preserved. If a cloze's text was genuinely changed, the data is treated as stale and regenerated (this is intentional). - Turn off **Force Regenerate Even if Data Exists** (General tab) to prevent overwriting existing data. ## A Card Shows `{"_skipped": true}` / "AI generation skipped" but I Never Skipped It - Newer versions (v8.4.0+) no longer write a skipped marker when a card only *temporarily* looks empty — for example a cloze you just created or edited, or an undo/new-cloze transition while reviewing. Such an attempt leaves the note unchanged. - If an older build already saved the marker (or you skipped the card deliberately), click **Clear** on the card. Clear is always rendered when the card holds AI-Hints data, and it removes both the marker and the `ai-hints::skipped` tag, so the card is eligible for generation again. - Still stuck? Check **Tools → AI Hints → Unskip AI for All Cards in Deck** for bulk clearing, and confirm the note actually contains a `{{c1::…}}`-style cloze for that ordinal — a card whose own cloze is absent from the note genuinely has nothing to generate from. ## Card Shows Hints/Options From a Different Question - Every AI write snapshots the card it targets, and a completion that arrives after you **cancel** the request or start a **newer** generation for the same card is discarded — including late "lingering" results. So an older run can no longer overwrite a newer one. - Pre-generated (background) results are also checked against the text they were generated from before being applied, so a cached result is dropped if the card changed in the meantime. - Editing a card **while** generation runs is allowed: that run still saves its result. If the text no longer matches, use **Generate/Regenerate** again (or `Alt`+click it to pick a specific model) to refresh the data. ## Old Card Style on AnkiDroid (WebView Cache) Android's WebView aggressively caches `_ai_hints_template.js`. See [Mobile Support → AnkiDroid Cache](mobile-setup.md#-troubleshooting-ankidroid-cache-webview). ## AnkiMobile Shows "undefined" When Tapping an Option This is fixed in v5.8.2+. Ensure your `_ai_hints_template.js` is up to date and keep a tap zone set to "Show Answer". See [Mobile Support → AnkiMobile](mobile-setup.md#-troubleshooting-ankimobile-undefined-on-tap). ## Batch Queue Stuck on 🌐 Offline All threads show **🌐 Offline** but the network works: the connectivity probe is a false negative. Hit **⚡ Force Start** in the Batch tab (one-run bypass), or tick **Ignore network/offline checks** under Advanced → Model Cooldowns & Blacklist for a permanent bypass. Parked threads pick up cards on their next wake cycle — pause/resume the queue to wake them immediately. ## Batch Generation Skipping Cards - Re-running a batch uses an **incremental per-deck cursor** and skips cards already generated. Use **Force FULL scan** to re-check everything. - Notes tagged with the `ai-hints` tag are skipped during fast scans. Use **Tag All Cards with Hints** to tag older cards. ## Where Are the Logs? - The **Logs** tab shows real-time logs with **Level** and **Source** filters — use the **Lingering** source filter to isolate the background linger-on-timeout lines (`AI-Hints Linger: ...`). Enable **Debug logging** there for full request/response payloads. - Log files are stored in `/ai_hints_bin/ai_hints.log` with 3-level rotation. See [Storage → Log Files](storage.md#5-log-files-ai_hintslog). ## Still Stuck? - Check the [Changelog](https://github.com/athulkrishna2015/AI-Hints/blob/master/changelog.md) for known fixes. - Report an issue: https://github.com/athulkrishna2015/AI-Hints/issues - Attach your log output (with Debug logging enabled) when reporting.