KOReader connects to BookShelves over your local Wi-Fi network — either via OPDS or Calibre wireless sync. When that connection doesn’t work, the cause is almost always one of a handful of common issues.
This guide walks through each problem and its fix, starting with the most frequent.
Quick checklist
Before diving into specific problems, verify these three things:
- Same Wi-Fi network. Your Mac and your e-reader must be on the same network. Guest networks, VPNs, and mobile hotspots often isolate devices from each other.
- BookShelves is running. The OPDS server or Calibre wireless server must be enabled in BookShelves Settings > Advanced. Look for the status indicator.
- Correct URL. For OPDS, the URL must end with
/opds(e.g.,http://192.168.1.100:8080/opds). For Calibre wireless, use just the IP and port (e.g.,192.168.1.100and9090).
If all three check out and it still doesn’t work, read on.
OPDS connection problems
“Connection failed” or blank catalog
Cause: KOReader can’t reach the BookShelves OPDS server.
Fixes:
Verify the IP address. Open BookShelves > Settings > Advanced and note the displayed URL. Your Mac’s IP changes when your router assigns addresses dynamically. If the IP changed since you set up KOReader, update the catalog URL.
Include the
/opdspath. The full URL should behttp://YOUR-MAC-IP:8080/opds. Without the/opdssuffix, KOReader loads the HTML web interface instead of the OPDS feed and shows an error or blank screen.Try adding a trailing slash. Some KOReader versions need
http://192.168.1.100:8080/opds/with a trailing slash. Try both with and without.Check your firewall. Go to System Settings > Network > Firewall. Make sure BookShelves is listed as “Allow incoming connections.” If it’s not listed, toggle the firewall off and on — macOS should prompt you to allow BookShelves the next time a connection comes in.
Try the
.localhostname. Instead of an IP address, use your Mac’s Bonjour name:http://your-mac-name.local:8080/opds. This survives IP address changes and works on any Apple network. Find your Mac’s name in System Settings > General > Sharing.
Catalog loads but shows no books
Your OPDS catalog is reachable but empty. This means:
- Your BookShelves library is empty. The OPDS server serves your actual library — it doesn’t have its own book collection. Import some books into BookShelves first.
- Books are still importing. If you just added books, BookShelves needs a moment to process metadata and covers. Wait a few seconds and refresh the catalog in KOReader.
Covers not loading
Book covers are served as separate image requests. On older e-ink devices or slow Wi-Fi, covers may take several seconds to appear. The books themselves download fine — this is purely a display speed issue on the device side.
Search not returning results
KOReader’s OPDS search requires at least two characters and matches against book title and author. If you’re searching for a single letter or a term that doesn’t match either field, you’ll get no results.
Calibre wireless problems
KOReader can’t find the server
Cause: KOReader’s Calibre wireless client can’t reach BookShelves.
Fixes:
Check the server is enabled. In BookShelves > Settings > Advanced, make sure the Calibre Wireless Server toggle is on. The status indicator should be orange (listening) or green (connected).
Enter the address manually. In KOReader, go to Calibre > Wireless Settings > Server Address > Manual. Enter your Mac’s IP and port 9090. Auto-discovery doesn’t always work across all router configurations.
Verify the port. The default is 9090. If you changed it in BookShelves, make sure KOReader matches. If another app is using 9090, change the port in BookShelves and update KOReader.
Check your firewall. Same as OPDS — make sure BookShelves is allowed through macOS firewall on port 9090.
Connection drops after a few minutes
The Calibre wireless server has a 5-minute idle timeout. If no books are being sent and no keepalive responses come in, the connection closes. This is normal behavior — reconnect from KOReader when you need to send more books.
Authentication error
The password in KOReader must exactly match what you set in BookShelves. The password is case-sensitive. If you’ve forgotten the BookShelves password, clear it in Settings > Advanced and set a new one, then update KOReader to match.
Books sent but not appearing on device
After sending a book, KOReader needs a moment to write the file to storage. On older e-ink devices this can take several seconds. Check KOReader’s file browser — sent books appear in the default Calibre library folder on the device.
If books still don’t appear, verify that your e-reader has enough free storage space.
Reading progress not syncing
Reading progress syncs when KOReader connects to BookShelves — not continuously in the background. To pull the latest progress, disconnect and reconnect from KOReader’s Calibre menu.
BookShelves matches books by author and title path. If the metadata differs significantly between your Mac library and the device, the match may fail. Make sure the book has the same title and author in both places.
Wi-Fi and network problems
Router isolates devices (AP isolation)
Many routers have a feature called AP isolation (or client isolation, guest mode, or Wi-Fi isolation) that prevents devices on the same network from communicating with each other. This is common on:
- Guest networks
- Public Wi-Fi
- Some mesh routers with default settings
- Corporate networks
Fix: Connect both devices to your primary home network, not a guest network. If your router has AP isolation enabled on the main network, disable it in your router’s admin panel (usually under Wireless Settings or Advanced Settings).
Mac on Ethernet, e-reader on Wi-Fi
If your Mac is connected via Ethernet cable and your e-reader is on Wi-Fi, they may be on different subnets depending on your router configuration. BookShelves binds to all network interfaces, but the IP address it displays is the Wi-Fi address.
Fix: Check which IP address KOReader can reach. Try both the Ethernet and Wi-Fi IP addresses shown in System Settings > Network. Or connect your Mac to Wi-Fi alongside Ethernet.
VPN interfering
If you’re running a VPN on your Mac, it may route local network traffic through the VPN tunnel, making your Mac unreachable from local devices.
Fix: Most VPN apps have a “local network access” or “split tunneling” option. Enable it so local network traffic bypasses the VPN. Or temporarily disconnect the VPN while syncing books.
IP address changed
Home routers assign IP addresses dynamically via DHCP. Your Mac’s IP can change after a restart, sleep, or when the DHCP lease expires.
Fix: Use your Mac’s .local Bonjour name instead of an IP address (e.g., http://chris-mac.local:8080/opds). This resolves automatically and survives IP changes. Alternatively, set a static IP or DHCP reservation for your Mac in your router settings.
Device-specific notes
Kindle
KOReader on Kindle requires jailbreaking the device first. If KOReader is installed but can’t connect to anything, make sure your Kindle’s Wi-Fi is actually connected — Kindle’s airplane mode aggressively disables Wi-Fi, and you may need to toggle it in the stock Kindle interface before switching back to KOReader.
Kobo
KOReader on Kobo runs alongside the stock firmware. Make sure you’ve launched KOReader (not the stock Kobo reader) before trying to connect. The stock Kobo reader does not support OPDS catalogs or Calibre wireless.
PocketBook
PocketBook devices running KOReader may need the OPDS URL entered without the http:// prefix in some firmware versions. Try both http://192.168.1.100:8080/opds and just 192.168.1.100:8080/opds.
Android
KOReader on Android should work the same as on e-ink devices. If you’re having trouble, make sure KOReader has network permissions (Settings > Apps > KOReader > Permissions on your Android device).
Still not working?
If none of the above fixes your issue:
Test from a browser. Open
http://YOUR-MAC-IP:8080in a web browser on any device on your network. If the BookShelves web interface loads, the server is reachable and the problem is specific to KOReader’s connection.Try a different OPDS client. Install Thorium Reader or another OPDS-compatible app and try connecting. If other clients work but KOReader doesn’t, the issue is on the KOReader side.
Check the KOReader wiki. The KOReader troubleshooting wiki covers device-specific issues that aren’t related to BookShelves.
Let us know. Report the issue on our feedback page with your Mac’s OS version, the KOReader version, your device model, and what you’ve tried. We’ll help diagnose it.
Related guides
- Send Books to KOReader over OPDS — step-by-step OPDS setup
- Sync Books with KOReader via Calibre Wireless — push books and sync reading progress
- How to Transfer Books to KOReader from Mac — overview of all methods
- BookShelves vs. KOReader — feature comparison
