Skip to content

Troubleshooting

Common Issues

Do I need Storyteller?

No. Storyteller is an optional integration. The bridge does audio ↔ ebook alignment itself using built-in Whisper transcription (or the EPUB's SMIL data), so cross-format sync works with just an audio source and an ebook client. Add Storyteller only if you actually use the Storyteller read-along app — the bridge will then sync its position and use its transcripts as a bonus alignment source.

An alignment is rejected, or opens at the wrong place

  • Confirm that the selected ebook and audiobook are the same edition. The Content-Match Guard deliberately refuses maps with too little shared wording; leave it enabled unless you know the pairing is a rough but intended match.
  • Open Settings -> Sync -> Alignment Health. A low-quality map can be rebuilt with Remap alignment, and Restore previous returns to the last saved map if the replacement is worse.
  • If a collection's audiobook narrates chapters in a different order from the EPUB, enable experimental Segmented Alignment Maps in Settings, then remap that book. It is off by default and is not needed for normally ordered books.

  • Forced alignment (on by default) matches each audiobook directly against its ebook and locates every chapter in the audio itself, so most books never touch Whisper. It falls back to transcription automatically for a book that is not in English, whose audio does not follow the text closely enough, whose chapters are narrated out of order, or that appears to be a different book — that fallback is expected, not a failure. To force-align a non-English book instead, choose the mms_fa model, which requires a self-built image (INSTALL_CTC=true) and effectively an NVIDIA GPU.

  • Completed transcripts are kept after alignment failure. Remap alignment reuses valid word timings instead of transcribing again. Certain older CWA input failures recover automatically only when the retained ebook and complete transcript prove the original pairing; otherwise manual review is required. See transcription recovery.

  • If local Whisper detects the wrong language, set Whisper Language under Transcription to a code such as ru or en. Filter Non-Speech Audio can reduce transcription over music and silence; test quiet narration first. Both affect new local transcriptions, not saved transcripts. Keep the Content-Match Guard enabled while checking the ebook and audio pairing.

Read-along highlights run ahead or stop partway through a sentence

Regenerate the read-along after upgrading to get complete sentence highlights and skip pages the narrator does not read. If the highlight gets increasingly ahead through the book, re-align the book first, then regenerate its read-along; the corrected alignment accounts for timestamp gaps between audio chapters.

KOReader sends progress under the wrong book

Install BridgeSync 0.9.9 on each device. Close affected managed books, then run Bridge Sync → Sync Reading Stats to repair their saved book identities. Positions and highlights are retained; do not delete the books' metadata to repair the checksum. The plugin also uses KOReader's metadata handling when managed books are renamed, replaced or removed.

A deliberate rewind does not stick

  • Confirm Honor a Deliberate Rewind is enabled under Settings -> Sync.
  • After going back, make some forward progress in the same app. One isolated backward report is intentionally held so a stale or echoed position cannot pull every reader backward.
  • If you want the furthest position to win in every case, turn the setting off.

Books are not showing up

  • Make sure your /books volume is mounted correctly in docker-compose.yml.
  • Check file permissions for the user running the container.
  • If the missing books should come from Grimmory, run Settings -> System -> Advanced -> Refresh Grimmory Cache.
  • If the missing books should come from BookOrbit, confirm BookOrbit is enabled, test the connection, and retry the matching flow.
  • If the missing books should come from CWA, confirm CWA is enabled, test the connection, and make sure the book is visible in Calibre-Web Automated.

Suggestions look stale or new imports are missing

  • A normal Scan Library run reuses cached results on purpose.
  • Use Full Refresh after large imports, removals, or metadata cleanup.
  • If Grimmory titles are missing from Suggestions, refresh the Grimmory cache first.
  • If BookOrbit titles are missing, confirm BookOrbit is enabled and reachable, then retry the scan.
  • If CWA titles are missing, confirm CWA is enabled and reachable, then retry the scan.

CWA progress is not syncing

  • Confirm CWA is enabled and the CWA server URL is reachable from the bridge.
  • Enable Kobo Sync in the CWA integration and enter the correct Kobo sync token for that reader.
  • If using custom polling, check the CWA sync poll interval and make sure it is not set higher than expected.
  • Confirm the book is linked to a CWA ebook entry; CWA progress only appears for books the bridge can resolve through CWA.

BookFusion progress or highlights are not syncing

  • Open Account -> My Integrations and confirm BookFusion is linked and enabled for that reader.
  • If you entered a token manually, BookFusion API keys are available from the BookFusion Calibre integration page.
  • Confirm the book is linked to a BookFusion book ID. If the book only exists locally, the dashboard link flow can Upload to BookFusion — this needs the reader's Calibre API key in My Integrations.
  • For highlights, also enable BookFusion -> Highlight Sync for that reader and keep the current Bridge Sync KOReader plugin installed on devices that should exchange annotations.
  • If using custom polling, check the BookFusion poll interval and make sure it is not set higher than expected.
  • Confirm the source is enabled and the audiobook still exists in the selected Grimmory or BookOrbit library.
  • For Grimmory, run Refresh Grimmory Cache after moving, rescanning, or replacing items.
  • For BookOrbit, confirm the item is still visible in BookOrbit and retry the matching or sync flow.
  • If the old source item was deleted and recreated with a new ID, rematch that book.

BookOrbit books are not matching or syncing

  • Confirm BookOrbit is enabled and configured in Settings, and use the Test button to check the connection.
  • If a book exists in BookOrbit but will not link, make sure it is visible in BookOrbit and that the bridge can reach the BookOrbit server.
  • If a book with more than one ebook format (e.g. an EPUB and a secondary KEPUB) keeps re-syncing on every cycle even though you have not moved, update to a current release — BookOrbit progress now consistently reads and writes the same primary ebook file instead of a secondary format that never caught up.
  • If you switched from Grimmory to BookOrbit, you do not need to rematch — run scripts/migrate_grimmory_to_bookorbit.py (see the Configuration Guide).

A read-along book keeps shifting position, or BookOrbit and BookBridge disagree

BookOrbit 3.0.0 and later syncs read-along books by itself. When one BookOrbit entry holds an EPUB 3 with media overlays and audio of matching length, BookOrbit keeps that entry's audiobook position, EPUB position, Kobo state and KOReader progress in step — and it does so from the same endpoints BookBridge writes to. On a book where BookBridge maps both formats onto that one entry, both would be writing it.

BookBridge detects this and steps back: it writes the ebook side only and lets BookOrbit move the audio position. You will see a line like:

🔗 'ebook-1a2b…' 'Title' BookOrbit read-along sync is active on entry 5180 —
   writing the ebook side only; the audio position is BookOrbit's mirror of that
   write, so it cannot lead or be written
  • This only applies when a book's audio and text are the same BookOrbit entry. If they are separate entries — the usual arrangement — nothing changes.
  • To have BookBridge drive both sides instead, set When BookOrbit syncs read-along books itself to Turn BookOrbit's off and drive both sides on the BookOrbit card in Settings, or switch the book's own read-along toggle off on its Details tab in BookOrbit. Note that BookOrbit's per-book default is on.
  • Point your KOReader devices at one sync server, not both. BookOrbit is a KOSync server in its own right, so a device syncing to BookOrbit and to BookBridge for the same book will see the two servers hand back different positions.

Hardcover or StoryGraph gets many requests, or a book never updates there

BookBridge posts a book's progress to a tracker once the book has been idle for that tracker's Update Cooldown. If the post fails — usually because the book has no match on Hardcover or StoryGraph — it retries after 15 minutes, then waits twice as long each time, up to every 6 hours, so an unmatched book costs only a few requests a day. Before 7.9.0 it retried on every sync cycle, which could add up to hundreds of Hardcover requests a night (#468).

To find the books affected, look in Logs for the reason followed by the retry:

⚠️ Hardcover: No match found for '<title>'
⏸️ '<book id>' Hardcover post failed at 42.0%; retrying in 15m (attempt 1)

Match the book by hand with Link to Hardcover or Link to StoryGraph on its card. New progress posts after the usual cooldown once the book is matched.

Highlights or notes are not syncing

  • Update the Bridge Sync KOReader plugin to the current release or newer on every KOReader device that should sync annotations.
  • Plain KOReader/KOSync progress sync does not sync annotations. In KOReader, use Tools -> Bridge Sync -> Sync Highlights or Sweep All Highlights.
  • Make sure Highlight Sync is enabled on the Settings -> Integrations -> KOReader / KoSync card.
  • For Grimmory web-reader annotations, enable Highlight Sync in that reader's Grimmory integration.
  • For BookOrbit web-reader highlights, fill in the BookOrbit KOReader sync username/password in that reader's Integrations and make sure the owner matches the BookOrbit user.
  • For BookFusion, enable BookFusion -> Highlight Sync in that reader's Integrations and confirm the book is linked to BookFusion.
  • For Readest, enable Readest -> Highlight Sync and enter that reader's Readest email/password.
  • For Hardcover, enable Hardcover -> Highlight Sync and enter that reader's Hardcover API token.

Bridge Sync uses too much memory or a device download fails

  • Update the Bridge Sync plugin to 0.6.10 or newer, then restart KOReader.
  • A failed replacement leaves the previous good book on the device. Run Sync books again after fixing network access; do not delete the existing copy first.

Books are not appearing in Readest

  • Uploading is off by default. Enable Upload matched books to Readest and/or Upload books you are currently reading in that reader's Account -> My Integrations.
  • The currently-reading sweep only sends books with a reading position above 0% and below the completion threshold. A book you have not opened anywhere will not be sent by it — match it with Upload matched books enabled, or start reading it.
  • Books already in that Readest account are skipped. Check the group named by Group name for uploaded books (default BookBridge).
  • The sweep shares a timer with the annotation syncs. If every one of those intervals is 0, set Upload: sweep interval (minutes) to a non-zero value so the timer runs.
  • Only EPUB files are uploaded.
  • If the Readest account is out of storage the log says so and uploading stops. Readest's free plan includes 500 MB; free space in Readest or lower Upload: max books per run.

Storyteller transcripts are not found

  • Verify the Docker volume is mounted as host Storyteller assets -> container /storyteller/assets.
  • In Settings, set Storyteller Assets Path to /storyteller, not /storyteller/assets.
  • Confirm the expected structure exists inside the container: /storyteller/assets/{title}/transcriptions/*.json.

Storyteller transcripts are still rejected

  • The bridge now accepts more Storyteller filename layouts, but the files still need real Storyteller timeline data.
  • Each chapter JSON should contain wordTimeline or compatible Storyteller timeline data.
  • If the filenames are right but the data format is wrong, the bridge will skip those files and fall back to SMIL or Whisper.

"Register" in KOReader or Readest says it failed, or the device still can't log in

BookBridge's built-in KoSync server does not create accounts from the device — sync accounts are set up in BookBridge's own Settings, on My Account → My Integrations. Tapping Register on the device now only succeeds if that account already exists there; otherwise it shows a message pointing you back to My Integrations instead of pretending to succeed.

  • Set a KoSync username and password under My Account → My Integrations → KOReader / KoSync, then use Login (not Register) on the device with those same credentials.
  • If you already did this and still see an error, work through KOReader cannot connect below — it is usually the address or the network path, not the account.

KOReader cannot connect: "Unknown server error"

KOReader reports Unauthorized when the address is right but the credentials are wrong, and Unknown server error when it never got a valid KOSync response at all — so this error is almost always the address, the port, or the network path, not the password.

Work through it in this order:

  1. Use the address BookBridge suggests. Open Account -> Connect a KOReader device. The suggested address is built from the address bar of the browser you are using, so it already carries the right port.
  2. Enter the base address only. No /api, /koreader, or /users/auth suffix — KOReader appends those itself.
  3. Default compose (8080:5757): http://<server>:8080
  4. Split-port mode: http://<server>:5758, but only with KOSYNC_PORT=5758 set and 5758:5758 published.
  5. Use the KOSync username and password from My Integrations — not your BookBridge web login, and not your Audiobookshelf account.
  6. Prove the path from another device on the same network:
curl http://<server>:<port>/healthcheck

It must return OK. If it does not, the problem is the Docker port mapping, the host firewall, or your VPN — not BookBridge. 5. Read the bridge log while the device retries:

docker compose logs -f | grep "KOSync Auth"
  • KOSync Auth: Failed auth attempt for user '<name>' from '<ip>' — the address works and the request arrived; the credentials are wrong.
  • KOSync Auth: Missing credentials from '<ip>' — the request arrived with no username/password headers at all.
  • No line at all — at the default LOG_LEVEL=INFO a successful auth is silent too, so this only means "no failure". If the device still reports an error, the request never reached BookBridge: go back to step 4. To see successes as well, set LOG_LEVEL=DEBUG and retry — a good login then logs KOSync Auth: User '<name>' authenticated successfully.

Connecting a Kindle or Kobo over Tailscale

  • Use the server's Tailscale IP (or MagicDNS name), not its LAN IP. The LAN address is unreachable once the device leaves the network.
  • The port still has to be the one you published. Tailscale does not change port mapping, so 8080:5757 still means :8080.
  • On a jailbroken Kindle running Tailscale through KUAL in userspace/proxy mode, starting Tailscale is not enough on its own. KOReader also has to be told to use the proxy: Settings -> Network -> HTTP proxy, set to http://localhost:1055, and enabled. Without this, KOReader's requests bypass the tunnel and fail with "Unknown server error" while other Tailscale checks look healthy.
  • Confirm the tunnel independently before blaming BookBridge: from the device's own network tools (or another tailnet device), fetch /healthcheck as shown above.

KOReader devices disagree on reading status, or a device's History stays empty

  • These features need the BridgeSync 0.9.6 plugin (or newer) on every device involved — older plugin versions do not send or receive the extra data.
  • Status (reading / finished / abandoned) is shared through Sync reading status between devices under Settings -> Integrations -> KOReader / KoSync. It is on by default. When two devices disagree, the one whose status changed most recently wins, and "finished" breaks a same-day tie.
  • Sharing History between devices is a separate, off by default switch — Share recently-read books between devices on the same card. Turning it on only adds books whose file is already on that device, nothing read more than 30 days ago, and at most 25 per sync, so a first run cannot bury your existing History.
  • Your reading position is never affected by either setting — only the status shown in the file browser, and what appears in History.
  • After a sync changes status or History, the bridge tells KOReader that book metadata changed, so the file browser (and shelf plugins that watch for that) should refresh on its own. If it still looks stale, restart KOReader.

KOSync split-port mode is not working

  • If you set KOSYNC_PORT, you also need to map that same port in Docker.
  • Example:
ports:
  - "8080:5757"
  - "5758:5758"

Transcription is taking too long

  • Use a smaller local Whisper model such as tiny.
  • If you have an NVIDIA GPU, enable GPU support as described in the Configuration Guide.
  • If Storyteller transcript assets are available, configure them so the bridge can skip Whisper entirely for those books.

Logs

You can inspect logs in the web UI or from the terminal:

docker compose logs -f

Useful places to look:

  • Match and Suggestions actions
  • Storyteller transcript ingest
  • Library refreshes
  • Background job failures

GPU Acceleration

See the Configuration Guide for NVIDIA GPU setup instructions.