Skip to content

troubleshooting

Jump to bottom
opencode edited this page Oct 4, 2026 · 1 revision

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.

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.

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 <profile>/ai_hints_bin/ai_hints.log with 3-level rotation. See Storage → Log Files.

Still Stuck?

Clone this wiki locally