FAQ & troubleshooting

Answers to common questions and fixes for the errors Kioku reports. Each entry pairs the symptom — the real message where Kioku shows one — with what to do about it.

Installing & launching

Windows blocks the installer with “Windows protected your PC”

The first time you run the installer or the portable build, Windows SmartScreen may show a warning.

To proceed, select More info, then Run anyway.

macOS won’t open the app

The first time you launch Kioku, macOS may block it.

To open it the first time, right-click (or Control-click) Kioku in the Applications folder and choose Open.

Which macOS download should I pick?

Pick the build that matches your processor:

Mac	Download
Apple Silicon (M1/M2/M3/M4)	the -mac-arm64 file
Intel	the -mac-x64 file

An Intel (x64) build runs on Apple Silicon through Rosetta but is slower; an Apple Silicon (arm64) build does not run on Intel Macs at all.

Note

Only x64 Windows builds are produced — there is no native Windows arm64 artifact. See the installation guide for the full list of downloads.

Importing

These cover importing a Source by URL, by PDF, or from HTML. For the workflow itself, see Import a web page.

”url must be a public http(s) URL (private, localhost, and non-http URLs are blocked)”

The address you tried to import is not a public web page. Only public http(s) pages can be imported; private, local, and non-web addresses are rejected, including after redirects.

Fix: import a publicly reachable http(s) URL.

”finalUrl must be a public http(s) URL (private, localhost, and non-http URLs are blocked)”

The original URL was public but redirected to an address that isn’t. Only public http(s) pages can be imported; private, local, and non-web addresses are rejected, including after redirects.

Fix: import the direct final URL, or a URL that does not redirect off the public web.

”Failed to fetch URL: ”

The remote server returned a non-OK HTTP status (for example 404, 403, or 500) when Kioku fetched the page or PDF.

Fix: confirm the URL opens in a browser. Paywalls and login walls commonly return 403. Retry once the page is reachable.

”Request timed out after 20000ms”

The fetch did not finish within Kioku’s 20-second import timeout. This affects both HTML and PDF fetches and most often appears with large remote PDFs on a slow connection.

Fix: check your connection and the host’s responsiveness, then retry.

”Response body exceeds maximum allowed size ( bytes)”

The content is over Kioku’s import size cap: 5 MB for HTML and snippets, 100 MB for PDFs.

Fix: use a smaller document. Split very large PDFs — textbooks near or over 100 MB — before importing.

”Could not extract article content from URL”

Kioku could not identify a main article body on the page. This is typical on JavaScript-rendered single-page apps, paywalled pages, link-list or index pages, and pages with no real article structure.

Fix: try a Live import (it loads the page at review time and captures Extracts from your selections instead of a static snapshot), or import the HTML snippet directly. See Static import / Live import.

”Failed to parse HTML: ” or “Failed to extract article: ”

The page’s markup could not be parsed, or extraction failed while reading it. This usually comes from genuinely malformed markup.

Fix: retry, try a Live import, or paste a cleaned HTML snippet.

”PDF contained no extractable text. Scanned/image-only PDFs are not supported.”

The PDF parsed correctly but produced no text — it is an image-only scan. Kioku’s PDF importer is text-only and does not run OCR.

Fix: run the PDF through OCR to produce a searchable text PDF, or import a born-digital PDF that already contains a text layer.

”Not a PDF file (missing %PDF- header). The URL or file did not return PDF bytes.”

The bytes Kioku received are not a PDF. This usually means a server returned an HTML error or login page under a .pdf URL, or a non-PDF file was renamed with a .pdf extension.

Fix: confirm the link actually serves a PDF rather than an HTML interstitial, and that the file is a real PDF.

”Failed to parse PDF: ”

Kioku could not load the document — a malformed or corrupt file, or a password-protected or encrypted PDF. Encrypted PDFs do not get a distinct message; Kioku supplies no password, so they surface here.

Fix: remove the password or re-save an unencrypted copy, repair the corrupt file, then re-import.

”Failed to read PDF file: ”

Kioku could not read the local PDF off disk — a missing file, a permissions problem, or a broken path. An empty path yields PDF file path is required instead.

Fix: confirm the file exists and is readable, then re-select it.

A PDF imports as “Untitled PDF”

Kioku derives a Topic title from the PDF’s metadata, then from its content, then from the filename. Only when all of those are empty does it fall back to Untitled PDF.

Fix: rename the file to something meaningful before importing, or edit the Topic title afterward in Browse.

A “Multi-column” badge appears on an imported PDF

Kioku detected a multi-column layout. Text from a two-column paper can come out interleaved or out of reading order. You see a one-time toast — PDF looks multi-column — extracted text may be out of reading order. View in Browse to verify. — and a persistent Multi-column badge in the PDF viewer footer.

This is a known limitation, not a crash.

Fix: verify the text in Browse.

My imported page lost its formatting, images, or styling

This is expected. Imported pages are cleaned to plain, readable content; active and embedded content is removed, while the text content is kept. There is no setting to disable this.

Fix: if you need the page’s original rendering or interactivity during review, use a Live import instead.

A Live-imported Topic looks almost empty and can’t be edited

This is expected. A Live import stores only the URL and title — no content snapshot — so the Topic body is intentionally near-empty and the real content loads at review time. The body is also read-only:

• In the Reader: Live imports stay read-only in Reader. Keep reading on the left and capture extracts or cloze cards from page selections.
• In Browse: Live imports are read-only in Browse. Use the header controls to open the live view for source-backed updates.

Fix: read and make Extracts or Cloze Cards from the live view. If you want a stored, editable snapshot, re-import the same URL as a Static import.

Live topic warning: “You’ve navigated to a different page. Choose import mode.”

While reading a Live Topic you followed a link to a different page. The banner offers Go Back, Import Static, or Import Live for the new page.

Fix: select Go Back to return to the Source page, or import the new page explicitly. To roam within the same site without this prompt, enable Thread mode on the Live import.

Live topic warning: “N previous extract(s) could not be found - the page content may have changed”

When you re-open a Live Topic, Kioku restores your saved Highlights onto the live page. If the page’s text changed since you made them, some Highlights can no longer be matched. This is informational — your Extract Cards still exist.

Fix: expected for sites that update. Re-create the Highlights against the current text if you need them. Static imports avoid this because they snapshot content.

Does re-importing the same URL create a duplicate?

No. Imports are de-duplicated by URL. Re-importing an existing URL updates the existing Source and Topic in place rather than creating a new one, so re-importing to refresh content is safe and won’t clutter Browse with duplicates.

”Masks cannot overlap. Move or resize existing masks first.”

In the image-occlusion Card editor, you drew, moved, or resized a mask so it overlaps another. Kioku blocks the change and shows this error, plus a throttled Mask overlaps an existing region toast.

Fix: reposition or shrink the masks so each occlusion region is separate. Overlapping regions are not allowed. See Card types.

Why can’t I create an Extract or Cloze from an Item?

Items are leaf flashcards. They have no children, are not valid drop targets, and have no create-from-selection actions; the details panel shows Children = N/A for an Item. Create-from-selection (Create extract with X, Create cloze with Z) lives in the Topic or Extract content editor and the Live-topic selection toolbar.

Fix: make new Extracts or Cards from the parent Topic or Extract. Edit the Item’s fields directly in the Item editor.

Reviewing & scheduling

Why is the “Begin review” button disabled?

On the Dashboard, Begin review is disabled when nothing is due. It reads Nothing to review when the Queue is empty, and Loading… or Unavailable while the session count is resolving.

Fix: import or create content, or wait until Items and Topics come due. To study specific material now, use the Review N button on a Browse search to start an ad-hoc session.

How are reviews split between cards and reading?

The split is governed by your review rhythm. The default, Fixed 3:1 (cards:topics), keeps a constant three Cards then one Topic. Ratio round robin follows the Topic ratio slider, and Global priority sorts all due content by priority. The Topic ratio only takes effect under Ratio round robin.

Fix: adjust Queue strategy and Topic ratio in Settings.

My intervals changed after I adjusted retention

Changing your retention target changes how often Items come due — higher retention means more frequent reviews, lower retention means fewer reviews but more lapses. This is expected.

Fix: if you want the change applied to existing Items immediately, Reschedule them. See Tune FSRS scheduling and Spaced repetition.

”Run optimization” is disabled

In Item scheduler, Run optimization is unavailable while it is already running, while you have unsaved retention changes, and until a minimum number of reviews exists. When the review count is too low, it shows how many reviews are available and the minimum required.

Fix: save any pending retention change first, and keep reviewing until you meet the minimum. Kioku tunes its scheduling to your review history and keeps the result only if it predicts your recall better. See Tune FSRS scheduling.

A keyboard shortcut isn’t doing what I expect

The same key can mean different things on different pages — for example, M toggles a bookmark in the Reader but sets the read point in a Review, and R refreshes in the Reader, marks a Topic read in a Review, and toggles rigid duration in a Plan. Some shortcuts also depend on context, such as a Topic being selected.

Fix: press H anywhere to open the shortcut help, which is also where you rebind keys. See Customize keyboard shortcuts and the keyboard shortcuts reference.

Data, backup & collections

Export dialog: “Media Not Included in .db Export”

When you export a Collection that contains image media as a .db file, Kioku shows a blocking warning — This collection contains image media assets. Exporting as .db will not include media files. A .db-only export drops the image files. The buttons are Cancel and Continue Export.

Fix: to keep images, use full Collection backup and restore instead of a .db-only export. See Back up and export your data.

Where does Kioku store my data?

Your collections, media, and backups live under Kioku’s app-data directory. The exact base path depends on your platform.

Fix: see the data locations reference for the per-platform paths.

How do I switch or manage Collections?

Collection management lives in Collections in Settings: switch the active Collection by selecting a row, and rename, show in the file manager, export, delete, create, or import from there. Deleting is hidden for the default Collection.

Fix: see Collections for how Collections isolate your data.

Reporting a bug

If something here is wrong, missing, or genuinely broken, use the Send feedback button under About in Settings. Include the exact error message, the steps that triggered it, your platform, and the app version (shown under About → Version).

The more precisely you can reproduce a problem — especially the exact error string — the faster it can be fixed.