Skip to content

❓ Troubleshooting & Frequently Asked Questions (FAQ) ​

Find quick, actionable solutions for common setup questions, network permissions, and configuration inquiries.


🌐 Notion Integration ​

Q: Why do I get "Could not find page with ID" or a 404 error when syncing Notion? ​

Cause: In Notion, creating an API token is only step one. Notion requires you to explicitly grant the integration access to your specific workspace pages.

Solution:

  1. Open the target Notion page or database in your browser or desktop app.
  2. Click the ••• (three dots) menu in the top-right corner.
  3. Scroll down and click Connections (or Connect to / Add connections).
  4. Select your Flashcard Master integration and confirm.
  5. All nested subpages will automatically inherit access.

⚡ Anki & AnkiConnect ​

Q: Why do I see "Connection Refused" when syncing to Anki? ​

Cause: Desktop Anki is either not running, or the AnkiConnect add-on is not installed.

Solution:

  1. Verify that Desktop Anki is actively running on your machine.
  2. Check that the AnkiConnect add-on is installed:
    • In Anki, go to Tools ➔ Add-ons.
    • Ensure AnkiConnect (code 2055492159) is listed and enabled.
  3. Verify that AnkiConnect is listening on the default local port (http://127.0.0.1:8765). If you changed the port in AnkiConnect config, update the URL in Flashcard Master Settings ➔ Anki Integration.

🗄️ Storage & Database ​

Q: Where are my cards and data sources stored? ​

All application state, documents, settings, and flashcards reside locally on your machine in an embedded SQLite database:

  • Default Database Location: ~/.flashcard-master/data.sqlite
  • Associated WAL Files: ~/.flashcard-master/data.sqlite-wal and data.sqlite-shm
  • Media Cache: ~/.flashcard-master/media/
  • Uploaded & Local Files: ~/.flashcard-master/local-files/

Desktop, Web UI, and CLI share ~/.flashcard-master/ automatically (CLI/Web can point to a different location with --data-dir <path>). To back up your entire knowledge base, simply copy ~/.flashcard-master/.


🤖 AI Models & Synthesis ​

Q: Why do some cards say "Discarded ungrounded card"? ​

Answer: This is a feature, not a bug! Flashcard Master enforces strict factual grounding via GroundingGuard. If an LLM hallucinates an answer or invents a fake quote that does not appear verbatim in your text, Flashcard Master catches and rejects it. The system then automatically backfills and synthesizes replacement cards that meet the strict verification criteria.

Q: Which AI provider should I choose? ​

  • For 100% offline privacy and zero cost, install Ollama and pull phi4-mini (ollama pull phi4-mini).
  • For blazing fast synthesis and massive document contexts, use Google Gemini (gemini-3.6-flash).
  • For concise board-exam style recall, use OpenAI (gpt-4o-mini).
  • For deep philosophical or conceptual synthesis, use Anthropic (claude-haiku-4-5-20251001).

🧵 Multiprocessing & Task Center ​

Q: Can I run multiple generation or ingestion tasks simultaneously? ​

Answer: Yes! Flashcard Master includes a dedicated background worker multiprocessing pool (WorkerExecutor):

  • By default, up to 2 background generation workers and 2 sync workers run in parallel as independent Node.js subprocesses.
  • You can tune concurrency limits (from 1 up to 16 workers) in ⚙️ Settings ➔ Worker Pool Concurrency Limits or via environment variables (MAX_GENERATION_WORKERS, MAX_SYNC_WORKERS).
  • Monitor active tasks, observe live token throughput, or cancel tasks anytime in the Task Center drawer (t shortcut).

🖥️ Desktop Installation & Operating System Warnings ​

Q: Why does Windows Defender SmartScreen say "Windows protected your PC / Unrecognized app"? ​

Cause: Windows Defender SmartScreen flags newly released binaries from the internet that do not yet have an accumulated download history or a commercial EV (Extended Validation) code-signing certificate.

Solution (Takes 5 seconds):

  1. In Edge or Chrome: If marked as "uncommonly downloaded", click the ... (three dots) next to the download → click Keep → click Show more → select Keep anyway (do not click "Report as safe", which opens an unnecessary feedback form).
  2. When opening the installer: On the blue "Windows protected your PC" dialog, click the underlined link: More info → then click the Run anyway button that appears.
  3. Alternative: Right-click the .exe file → select Properties → check Unblock at the bottom of the General tab → click Apply / OK.

Q: Why does macOS show "cannot be opened because the developer cannot be verified"? ​

Cause: Apple Gatekeeper flags applications downloaded outside the Mac App Store that are not notarized with an Apple Developer ID.

Solution:

  1. Open System Settings → Privacy & Security.
  2. Scroll to the Security section and click Open Anyway next to Flashcard Master.
  3. Alternatively, in Finder, right-click (or Control-click) Flashcard Master.app in /Applications and select Open, then confirm.

Q: Where can I find all release installers and updates? ​

All release assets (including Windows .exe, macOS universal / Apple Silicon / Intel .dmg, and Linux .deb / .AppImage packages) are cataloged on the Flashcard Master GitHub Releases Page.


🎙️ Audio, Video & YouTube Ingestion ​

Q: How do I check if ffmpeg, yt-dlp, and whisper-local are ready? ​

Open ⚙️ Settings ➔ General ➔ Speech-to-Text & Media Defaults and click 🔍 Check Readiness (or call GET /api/settings/media/diagnostics).

  • ffmpeg: Required for local video audio extraction, embedded subtitle probing, and pre-STT timestamp range trimming.
  • yt-dlp: Used for YouTube subtitle/audio fallback when direct caption fetches are blocked or empty. If yt-dlp is not installed on your PATH, Flashcard Master can automatically download and cache a standalone binary on demand.
  • whisper-local: Requires either a running whisper.cpp HTTP server (configured via Local Whisper Endpoint) or a whisper-cli / main binary on PATH / WHISPER_BINARY_PATH.

Q: Why did YouTube sync fall back to Speech-to-Text even though the video has captions? ​

Some YouTube caption tracks return empty cues on direct timedtext requests or are auto-generated only. In auto extraction mode, Flashcard Master tries:

  1. Creator captions (en / configured defaultSubtitleLanguage),
  2. yt-dlp subtitle download (--write-subs --write-auto-subs), and
  3. Audio download via yt-dlp followed by your configured Speech-to-Text provider (openai, gemini, or whisper-local).

Q: Why did YouTube chapters slicing produce fixed N-minute slices? ​

Flashcard Master extracts chapters from both YouTube video descriptions and ytInitialData player markers (AUTO_CHAPTERS and MACRO_MARKERS_LIST_RENDERER). If a video has neither creator-defined description timestamps nor YouTube chapter markers, the slicing engine gracefully falls back to fixed Time Windows (intervalMinutes, default 10 minutes) so long transcripts are still cleanly segmented.

Released under the GNU Affero General Public License v3.0 (AGPL-3.0).