calibre OPDS Catalog Not Loading: How to Fix It

When a calibre OPDS catalog is not loading in an e-book reader app, the failure usually falls into one of a few categories: the calibre Content server is not running, the app is using the wrong OPDS address, authentication is failing, the devices cannot communicate across the network, or the reader app has cached an outdated connection. The fastest solution is to test each layer separately rather than reinstalling calibre or changing several settings at once.

This guide focuses specifically on OPDS catalog access. It applies when an OPDS-capable reader cannot browse the catalog exposed by calibre's Content server, even though your books may still appear normally in the calibre desktop application. Follow the checks in order and stop as soon as the catalog loads successfully.

1. Confirm the Symptom With a Small Safe Test

Begin by determining whether the problem is with calibre, the network, or the reader app. A short browser test provides more useful information than repeatedly refreshing the OPDS client.

1.1 Verify That the Content Server Is Running

In calibre, open the Connect/share menu. If the menu offers Start Content server, the server is currently stopped. Start it and wait a few seconds. If the menu offers Stop Content server, it is already running.

Next, open a web browser on the same computer as calibre and enter:

http://127.0.0.1:8080

Replace 8080 if you configured a different Content server port. Success means that the browser displays the calibre server interface or prompts for the username and password you configured. If the local address does not open, do not change the reader app yet. The fault is on the server computer or in the Content server configuration.

1.2 Test the OPDS Endpoint Directly

An OPDS reader normally needs the OPDS endpoint rather than only the server's main browser address. With the default port, test this address in a browser on the calibre computer:

http://127.0.0.1:8080/opds

The result may appear as a structured feed, an XML-style document, a download, or a browser-rendered catalog. Its appearance depends on the browser. The important result is that the server responds without a connection error, authentication loop, or not-found message.

If the main server page opens but /opds does not, confirm that you typed the path correctly. It begins with a forward slash and uses lowercase letters. If you operate calibre behind a reverse proxy or URL prefix, the required address may instead resemble https://example.com/calibre/opds. The prefix used by the proxy must also appear in the OPDS URL.

1.3 Test From the Reader Device's Browser

Find the local IP address of the computer running calibre, such as 192.168.1.25. On the phone, tablet, or other reader device, open a browser and visit:

http://192.168.1.25:8080

Then test:

http://192.168.1.25:8080/opds

Do not use 127.0.0.1 or localhost on the reader device. Those names refer to the reader device itself, not to the computer running calibre.

If the catalog opens in the device's browser, calibre and the basic network path are working. Stop changing calibre's firewall, library, or server settings. Concentrate on the OPDS reader's URL, credentials, security requirements, and cache. If the address fails in the device browser, continue with the server and network checks below.

2. Check the calibre Settings Directly Related to OPDS

The Content server settings control whether an OPDS client can reach the catalog and whether it must authenticate. Conversion settings, metadata-download providers, e-mail delivery accounts, the e-book editor, and USB device detection generally do not control whether the OPDS feed opens.

2.1 Confirm the Port and Listening Address

Open Preferences, find Sharing over the net, and review the server port. The URL entered in the reader must use the same port. For example, a server configured for port 9090 will not answer through port 8080.

If you have deliberately configured the server to listen only on 127.0.0.1, other devices cannot connect directly. That setting is appropriate when a reverse proxy on the same computer is the only intended client. For direct home-network access, the server must listen on an interface reachable from the network.

Success means the device browser reaches the server using the computer's local IP address and configured port. Once it does, avoid experimenting with unrelated network-interface settings.

2.2 Use the Expected OPDS URL Path

Many reader apps ask for a catalog URL, not merely a website address. A typical direct OPDS address is:

http://COMPUTER-IP:PORT/opds

For example:

http://192.168.1.25:8080/opds

Common address mistakes include:

• Entering localhost or 127.0.0.1 on a separate device
• Leaving out /opds when the app expects a feed endpoint
• Using the wrong port
• Entering https even though the local server is providing plain http
• Omitting a reverse-proxy prefix from the URL
• Copying an old IP address after the server computer received a new one

Some apps can discover OPDS feeds automatically through network discovery, but manual entry is usually more reliable for troubleshooting. If the manually entered URL works, you can stop adjusting calibre and leave automatic discovery disabled if it remains inconsistent.

2.3 Check Authentication Settings

If Require username and password is enabled, the OPDS app must send credentials accepted by the Content server. Re-enter the username and password rather than relying on stored values. Check capitalization, accidental spaces, and whether the app has separate fields for server credentials.

First test the same credentials through the reader device's browser. If the browser accepts them but the reader app repeatedly asks for a password, the app may not support the server's authentication method correctly. Check whether the app documents compatibility with authenticated OPDS catalogs.

If appropriate for a brief test on a trusted private network, you can temporarily disable authentication, restart the Content server, and retry the catalog. Do not leave authentication disabled if the server is reachable from the public internet or an untrusted network. If disabling authentication makes the catalog load, the network and OPDS path are working, and the remaining issue is credential storage or authentication compatibility.

2.4 Confirm the Correct Library Is Being Served

If the feed opens but appears empty or shows the wrong books, verify which library the Content server is exposing. This is particularly important if you switch between multiple calibre libraries or run the standalone calibre-server command with an explicit library path.

Open the main server interface in a browser and inspect the available libraries. If the expected library appears and its books can be browsed, the Content server has access to it. If the library is missing, switch to the intended library in calibre or correct the library path supplied to the standalone server.

Missing covers, imperfect author names, or incomplete descriptions are metadata issues, but they normally should not prevent the catalog itself from opening. Repair metadata only after basic OPDS navigation works.

3. Check the Network, Firewall, and Reader App

If the server works on the calibre computer but not on another device, the problem is usually between the two devices. USB mode, e-mail delivery, and book conversion are not part of this connection because OPDS access travels over the network.

3.1 Confirm Both Devices Are on the Same Reachable Network

Connect the calibre computer and reader device to the same home or office network for the initial test. A phone using cellular data is not on the same local network as a computer connected to home Wi-Fi. Similarly, a guest Wi-Fi network may isolate clients and prevent them from contacting one another.

Temporarily disable cellular data on the mobile device and retry the local IP address. If your router has separate guest and primary networks, place both devices on the primary network. Also check whether a VPN is active on either device, since some VPN configurations block local network access.

Success means the server's main page and /opds endpoint open in the reader device's browser. At that point, stop changing router and firewall settings and return to the reader app.

3.2 Allow calibre Through the Firewall

Windows, macOS, Linux firewall tools, and third-party security suites can allow local access on the server computer while blocking incoming connections from other devices. Ensure calibre or the standalone Content server is allowed to accept connections on the selected network and port.

On Windows, confirm that calibre is allowed on the active private network profile. Avoid enabling broad public-network access unless it is actually required. On macOS, review incoming connection permissions in the firewall settings. On Linux, check the active firewall service and allow the configured TCP port from the trusted local network.

If security software provides its own firewall, its rule may take precedence over the operating system's rule. A brief, controlled test can help identify interference, but do not leave antivirus or firewall protection disabled. Create a narrow rule for calibre or its port instead.

3.3 Check Wireless Isolation and Changing IP Addresses

Routers may use settings named client isolation, access-point isolation, wireless isolation, or guest isolation. These features intentionally stop Wi-Fi clients from communicating with local devices. Disable the relevant isolation feature only on a trusted private network.

The computer's local IP address can also change after a restart or router reconnection. If an old catalog entry suddenly stops working, compare the current computer address with the address stored in the reader app. Consider creating a DHCP reservation in the router after confirming that an address change caused the problem.

3.4 Clear or Recreate the Reader App's Catalog Entry

OPDS apps may retain an old address, rejected certificate, failed authentication response, or stale catalog data. If the feed works in the device browser, delete the saved catalog entry in the reader app and create it again using the confirmed URL.

If the app provides a cache-clearing or refresh command, use that before clearing all application data. Clearing all data may remove downloaded books, reading positions, and preferences, so reserve it for cases where the app's documentation confirms what will be erased.

Success means the app displays the catalog's navigation entries, libraries, authors, titles, or books. Once browsing works, do not reinstall calibre or rebuild the library simply because covers take a moment to appear.

3.5 Consider Reader-App Security Limitations

Some operating systems and reader apps restrict unencrypted HTTP connections, reject self-signed HTTPS certificates, or support only certain authentication behavior. If the same OPDS URL opens in a browser but not in the app, inspect the app's error message and documentation for requirements involving HTTP, HTTPS, certificates, or local network permission.

On mobile systems, verify that the app has permission to access the local network when that permission exists. If an app cannot support your server's connection type, test with another OPDS-capable client before making major changes to calibre.

4. Use Logs and Controlled Diagnostics

Logs are most helpful after you know whether a request reaches the server. They can distinguish a blocked connection from a rejected login, incorrect path, or internal server error.

4.1 Interpret Whether Requests Reach the Server

If the server records no request when you refresh the OPDS app, the traffic is not reaching calibre. Recheck the IP address, port, Wi-Fi network, VPN, router isolation, and firewall.

If a request appears with an authentication failure, correct the credentials or test authentication compatibility. A not-found response suggests an incorrect path or reverse-proxy prefix. A server error associated with one catalog action may point to a library, template, plugin, or server configuration problem.

For a standalone server, the calibre-server command supports server and access logging options. Use an access log to see incoming requests and a server log to capture operational errors. Avoid publishing logs without reviewing them because they may contain usernames, IP addresses, library names, or requested book information.

4.2 Start calibre With Debug Output When Necessary

If the graphical application or Content server behaves unexpectedly, launch the calibre GUI from a terminal or command prompt with:

calibre-debug -g

Reproduce the problem and inspect the output for a concrete error. This is more useful than assuming that every calibre issue requires a reinstall. Plugins can be relevant if debug output names a plugin or if the problem began immediately after installing or updating one, but random plugin removal is not a good first step for a network-access symptom.

4.3 Separate Feed Problems From Book Problems

If the catalog opens but one book fails to download or open, OPDS access itself is working. Test another book with a common format supported by the reader. A failure limited to one title may involve the source file, its filename, the available formats, or the reader's format support.

Conversion settings are relevant only if you must create a format compatible with the device. They do not normally repair a catalog that cannot connect. Likewise, metadata downloads, e-mail accounts, USB detection, news downloads, viewer settings, and editor settings should be left unchanged unless the failure occurs specifically in those functions.

5. Run a Clean Temporary Test Before Reinstalling

Reinstalling calibre usually does not correct a wrong URL, blocked port, stale app entry, or network-isolation setting. A clean test can identify the failing layer without risking your main library.

5.1 Build the Smallest Useful Test

1. Create a temporary local folder for a test library.
2. Switch calibre to that library without deleting or moving your normal library.
3. Add one DRM-free test book that you are permitted to use.
4. Start the Content server with a known port.
5. Open the main server page and /opds locally.
6. Open both addresses in the reader device's browser.
7. Add the confirmed OPDS URL to the reader app.

If the temporary catalog works, the application installation, network, and reader app can communicate. Compare the main library's server visibility, location, permissions, templates, and plugin behavior. If the temporary catalog also fails, focus on the server settings, firewall, network, authentication, and app compatibility.

5.2 Avoid Testing From a Cloud-Synchronized Library

For the clean test, use a normal local folder rather than a cloud-synchronized, network-mounted, or removable location. Synchronization tools can lock files, delay changes, or create conflicting copies. Although these problems are more likely to affect library updates than basic OPDS connectivity, a local test removes that variable.

Do not delete metadata.db, erase your library, or bulk-move book folders as an OPDS troubleshooting step. Back up the library before making structural changes, and make such changes only when evidence points to library corruption or filesystem trouble.

5.3 Know When to Stop

Stop changing settings when the device browser can open /opds and the reader app can browse the catalog. Slow cover loading, a book-format limitation, or an isolated title error is a separate issue. Treating every later symptom as a server-connection failure can undo a working configuration.

6. Quick Fix Checklist

• Confirm calibre shows the Content server as running.
• Open http://127.0.0.1:PORT on the calibre computer.
• Open http://127.0.0.1:PORT/opds on the calibre computer.
• Use the computer's local IP address on the reader device.
• Confirm the reader app's URL includes the correct port and /opds.
• Place both devices on the same non-isolated network.
• Test the server URL in the reader device's browser.
• Re-enter the Content server username and password.
• Allow calibre through the firewall on the trusted network.
• Temporarily disconnect VPNs that block local access.
• Delete and recreate the reader app's saved catalog entry.
• Check logs before changing plugins or library files.
• Use a temporary local library before reinstalling calibre.

7. Frequently Asked Questions

7.1 What Is the Correct calibre OPDS URL?

For a direct local connection, the usual pattern is http://COMPUTER-IP:PORT/opds. With a computer at 192.168.1.25 and the default port, that becomes http://192.168.1.25:8080/opds. If you use a reverse-proxy prefix, include it before /opds.

7.2 Why Does calibre Open on the Computer but Not on My Phone?

The server may be listening only for local connections, the firewall may be blocking incoming traffic, or the devices may be on isolated networks. Test the computer's local IP address from the phone's browser. Do not use localhost or 127.0.0.1 on the phone.

7.3 Why Does the Catalog Work in a Browser but Not the Reader App?

This result usually points to the reader app's saved URL, cache, authentication support, HTTP policy, certificate handling, or local-network permission. Recreate the catalog entry and enter the tested URL and credentials manually. If it still fails, test another OPDS client before changing calibre.

7.4 Does an Empty OPDS Catalog Mean My Library Is Corrupt?

Not necessarily. Confirm that the Content server is exposing the intended library and that no user-account restrictions hide it. If the server's browser interface shows the expected books, the library is accessible. An empty app view may be stale cached data or a navigation compatibility problem.

7.5 Should I Reinstall calibre?

Reinstallation should be a late step. It will not normally fix an incorrect IP address, wrong port, blocked firewall rule, failed authentication, guest-network isolation, or stale reader-app entry. Run the local browser, device-browser, and temporary-library tests first.

7.6 Are Conversion or Metadata Settings Causing the Catalog Failure?

Usually not if the catalog cannot connect or browse at all. Conversion becomes relevant after the catalog works but the reader cannot use an available book format. Metadata settings may affect titles, authors, covers, and descriptions, but they generally do not determine whether the OPDS endpoint can be reached.