Troubleshooting

AnkiConnect errors¶

Symptom: Connection error when trying to push cards.

Cause: Anki is not running, or AnkiConnect is not installed.

Fix:

1. Open Anki.

2. Confirm AnkiConnect is installed (Tools → Add-ons).

3. Verify it is listening: open http://localhost:8765 in a browser.

Poor OCR quality¶

Symptom: Incorrect text, garbled labels, or missed regions.

Fixes:

• Add the correct language code: --langs en,es for Spanish images.

• Use --smart to let Claude correct OCR errors automatically.

• Ensure the source image is high resolution:OCR quality drops significantly on low-res images.

Too many small occlusion boxes¶

Symptom: Every word becomes a separate occlusion; boxes are not grouped.

Fix: Increase merge thresholds in your config or via CLI:

niobium --directory ./images --deck-name MyDeck --merge-lim-x 20 --merge-lim-y 20

Or set higher values in your config:

merge:
  enabled: true
  limit_x: 20
  limit_y: 20

Smart mode falls back to rule-based filtering¶

Symptom: Niobium prints “Falling back to rule-based filtering.”

No images extracted from PDF¶

Symptom: Zero images extracted from a PDF.

Cause: The PDF pages contain only vector graphics or text rendered as outlines:not embedded raster images.

Fix: Convert PDF pages to raster images using an external tool (e.g., pdftoppm) and then use --directory mode.

Cache not working¶

Symptom: Images that were already processed are being reprocessed.

Possible causes:

• --no-cache is set on the command line

• The image file was modified (changes its content hash)

• The cache was cleared with --clear-cache

Fix: Remove --no-cache if present. If the file content changed, Niobium correctly treats it as a new image.

EasyOCR first-run download¶

Symptom: First run takes several minutes before processing starts.

Cause: EasyOCR downloads PyTorch and language model weights on first use.

Fix: This is expected. Subsequent runs use the cached models and start much faster.