Troubleshooting
Start with the symptom below, preserve the relevant logs, and make the least destructive change first. The linked pages own the complete setup and configuration details.
Container Does Not Start
Symptom: The container stops before the web interface becomes available, restarts repeatedly, or reports a configuration or permission error.
Likely cause: JWT_SECRET is missing or still the placeholder from shisho.example.yaml; another setting fails validation; a persistent path is not mounted or writable; the database cannot be opened; or the configured listener address cannot be bound. Validation failures include a duration without a unit or below 1ms, such as database_busy_timeout: 5000 instead of 5s; worker_processes below 1; a negative database_max_retries or database_connect_retry_count; and an enrichment_confidence_threshold outside 0 to 1.
Verify: Read the container's startup output before restarting it again. A setting with an invalid value, including a duration without a unit from YAML or an environment variable, prints configuration validation failed followed by each setting, its environment variable, and the allowed range or format. A value of the wrong type, such as text where a number belongs, prints failed to unmarshal config with the setting name instead. Confirm that /config is persistent, any custom database path is inside a writable mount, and JWT_SECRET is set without printing its value into a support request. Check listener errors against SERVER_HOST and SERVER_PORT. If the container is still running but unhealthy, check whether migrations are still running and whether the health check targets the configured port.
Fix: Follow the Compose and secret-configuration steps in Getting Started. Correct each setting the validation error names; see Configuration for the duration format. Replace a placeholder secret with the output of openssl rand -hex 32. Changing the secret signs everyone out once. A secret shorter than 32 characters does not stop startup, but the startup log and Administration > Server warn about it; replace it the same way. Match the container's PUID and PGID to the host files, correct the mounts, and review startup and database settings in Configuration. See Deployment and Maintenance before moving an existing database or changing storage.
Changing JWT_SECRET invalidates existing signed sessions. Generate and store a strong secret, but do not rotate it merely to troubleshoot an unrelated startup problem.
Scans Report Permission Errors or Files Move Unexpectedly
Symptom: A scan cannot read books, cannot write covers or sidecars, or files and directories are renamed or moved.
Likely cause: The container user cannot access the media mount, the mount is read-only for an operation that writes files, or Organize file structure during scans is enabled for the library.
Verify: Check the library's configured container paths, the media mount mode, and the host ownership represented by PUID and PGID. In Administration > Libraries, open the library and check whether file organization is enabled. Review the failed scan's job log for the exact path and operation.
Fix: Grant only the access Shisho needs. Read access is required to scan. Write access is required for file organization and other operations that write beside library files. Disable file organization before another scan if Shisho must not rename or move files. See Getting Started, Libraries, and Managing Books and Files.
Before enabling file organization, back up the library and test the setting on a small library. Do not grant broad write access as a substitute for identifying the failing path.
New Files Are Missing After a Scan or Monitor Event
Symptom: Files copied into a library do not appear automatically, or a manual scan finds files that the real-time monitor missed.
Likely cause: The host path is not mounted at the path configured for the library, the file type is unsupported, the file's content does not match its extension, the monitor is disabled, a network filesystem does not deliver filesystem events, the monitor delay has not elapsed, or Linux exhausted its inotify watches.
Verify: Confirm the file is visible at the configured path from the container and compare its extension with Supported Formats. Run a library scan. If the scan finds the file but monitoring does not, inspect the monitor settings and current-session server logs. On Linux, check for inotify watch errors. Network storage that misses events points to a monitor limitation rather than a parser failure.
Fix: Correct the mount or library path, wait for the configured monitor delay, or increase the Linux watch limit as documented in Configuration. For network filesystems that do not support reliable events, disable the real-time monitor and rely on scheduled or manual scans. See Libraries and Deployment and Maintenance.
A DRM-Protected File Never Appears
Symptom: A .mobi, .azw, .prc, .azw3, .kepub.epub, or .kepub file is in a library folder, but no book appears for it after a scan. If the file had been imported before, its book or file disappears after the file is replaced.
Likely cause: The file is DRM-protected. Shisho never imports DRM-protected files and cannot read them. When an imported file is replaced on disk by a DRM-protected copy, the next scan removes it as if the file had been deleted.
Verify: Open the scan job under Administration > Jobs and look for a skipped DRM-protected file warning naming the file. A mime type is not expected for extension warning for the same path means the file is not MOBI or AZW3 at all, for example a KFX book with an .azw extension; see Supported Formats.
Fix: Replace the file with a DRM-free copy. A plugin input converter that declares mobi, azw3, epub (for a .kepub.epub), or kepub (for a .kepub) still receives DRM-protected files and can write a DRM-free copy beside them, which the scan then imports.
A File Is Marked Unreadable
Symptom: A file shows an Unreadable badge on the book page, or the file's page shows a "This file could not be read" notice. The scan job log contains failed to parse file metadata for the same path, often with zip: not a valid zip file for EPUB and CBZ files.
Likely cause: The file on disk is damaged. The most common case is a zip-based file (EPUB, CBZ) whose central directory was cut off by an interrupted copy or a reader application that rewrote the file over a network share. The book keeps the metadata from the last successful scan, but the in-app reader and KePub conversion will fail for that file until it is repaired.
Verify: Run unzip -t on the file. A truncated archive reports that it cannot find the end-of-central-directory signature.
Fix: For a truncated zip, the content entries are usually intact and zip -FF can rebuild the archive:
zip -FF "Book.epub" --out "Book.repaired.epub"
unzip -t "Book.repaired.epub"
mv "Book.repaired.epub" "Book.epub"
Otherwise replace the file with a good copy. Shisho picks up the change on the next monitor event or scan, refreshes the metadata, and clears the badge. The book keeps its existing metadata and sidecar while the file is unreadable.
A Comic's Cover Page or Chapters Point at the Wrong Page
Symptom: In a CBZ file, a chapter link opens the wrong page, Select page highlights a page other than the cover, a KePub download shows a different cover than Shisho does, or the last pages in the reader show a broken or blank image.
Likely cause: The file was scanned by Shisho 0.1.1 or earlier. Those versions counted pages in plain character order, so page10.jpg came before page2.jpg, and counted macOS metadata files as pages. Shisho now counts pages as described in Supported Formats, so the reader shows the pages in order, but the cover page, chapter start pages, and page count recorded by the earlier scan keep their old values. A library scan does not change them, because it skips files that have not changed on disk.
Verify: Run unzip -l on the file. Files that can be affected have page or folder names whose numbers are not zero-padded, such as page1.jpg through page10.jpg, or contain ._ files or a __MACOSX folder.
Fix: On the book page, open the file's actions menu and choose Rescan file. Scan for new metadata corrects the page count and keeps your manual edits, but leaves the chapters as they are. Refresh all metadata also detects the chapters again. It replaces chapters you edited by hand, so edit them again afterward, and it does not change the cover page. To fix the cover page, open Edit on the file, choose Select page, and pick the cover again. Reset to file metadata recomputes both the cover page and the chapters, but it also removes the file's manual edits and plugin metadata; see Metadata.
A Background Job Failed
Symptom: A scan, download, hash, or plugin-related job is marked Failed.
Likely cause: The job log usually identifies a file permission, missing path, parser, plugin, storage, or database error.
Verify: Open Administration > Jobs, select the failed job, and read its job log. Job logs belong to that persisted job and remain subject to the configured job-retention period. Administration > Logs shows the in-memory server log for the current server session. It may contain surrounding startup or request context, but it is cleared when the server restarts. Slow database queries appear there as slow query warnings with the operation, table, and duration. To see every SQL statement, enable database_debug only briefly: it logs parameter values, including password hashes and share tokens, to that page. See Configuration.
Fix: Correct the first actionable error in the job log, then retry the original task. Use current-session server logs for context, not as a replacement for the job's own history. See Deployment and Maintenance, Configuration, and Users and Permissions for access to administrative pages.
The Database Reports That It Is Locked
Symptom: Startup or a request repeatedly reports database is locked, SQLITE_BUSY, or SQLITE_LOCKED after Shisho's wait and retry handling.
Likely cause: More than one Shisho process is using the same SQLite file, another program is holding it open for writes, or the database is on storage with unreliable SQLite locking.
Verify: Confirm that only one Shisho instance points at the database file. Check whether backup, sync, or database tools are operating on the live file. Note whether the database lives on a network filesystem.
Fix: Stop the competing writer and keep a single Shisho instance attached to the database. Follow Deployment and Maintenance for safe backups and storage placement. The busy timeout and retry settings are documented in Configuration; increasing them may help short contention, but it does not make multiple writers or unreliable storage safe.
Do not delete the database or its related files to clear a lock. Back it up before moving it or attempting recovery.
Downloads or Readers Fail, or Cache Usage Is High
Symptom: A generated download fails, a reader cannot render pages, a stale generated file is reused, or the cache consumes unexpected disk space.
Likely cause: The cache path is full or not writable, the source media is no longer readable, generation failed in a background job, or cached generated output needs to be rebuilt after its producer changed. A file or cached copy that exists but cannot be read, such as one whose permissions deny the Shisho user, returns 500 Internal Server Error; 404 Not Found means the file is missing from disk. When a generated copy cannot be made from a file's contents, OPDS, eReader, Kobo Sync, and Share Link downloads send the original file instead and log a warning, so an unchanged download on a device can also point to a generation failure. A conversion to another file type fails with an error instead of sending the original when it was picked by OPDS, the eReader Browser, or Kobo Sync through Delivery Rules, such as EPUB delivered as KePub, or from a Share Link's Download as menu; no device sends the original for a failed conversion, and the server log names the file.
A generated file that fails after its download has started ends that download with a connection error, so no truncated file is saved, and logs a warning naming the file. Shisho remembers the failure, even across restarts: later downloads on devices and Share Links get the original file, or an error for a conversion through OPDS, the eReader Browser, Kobo Sync, or a Share Link's Download as menu, and the web app shows the error with a Download unmodified file button. Editing the book's metadata, or clearing the download cache, makes the next download try again.
A download cache that is full or not writable does not stop downloads. Each download is generated straight to the client without being cached, and a warning is logged; the next download of the same file is generated again.
Verify: Check Administration > Jobs for the generation job, Administration > Cache for cache size, the current-session server logs for request errors, and available space and permissions at cache_dir. Confirm that the original file remains readable.
Fix: Correct storage or permissions first. Clear only the affected cache from Administration > Cache when regeneration is appropriate. Clearing cache removes generated copies, which Shisho rebuilds on demand, and may make the next request slower. See Supported Formats, Deployment and Maintenance, and the cache settings in Configuration.
Login, Links, or Cookies Break Behind a Reverse Proxy
Symptom: Login succeeds and immediately appears logged out, generated links use the wrong scheme or host, or the main interface works while API or device routes return the frontend page or a proxy error.
Likely cause: The proxy is not preserving the public host and HTTPS scheme, Shisho does not trust the proxy's direct peer address, the browser and server are switching between HTTP and HTTPS, or the proxy strips or misroutes endpoint prefixes.
Verify: Confirm the public URL stays on one scheme and host. Inspect whether the proxy preserves Host and supplies X-Forwarded-Proto and X-Forwarded-Host. Check the proxy's direct connection address against the forwarded-header trust rules. Confirm requests under /api/, /opds/, /kobo/, /ereader/, and /e/ reach Shisho without stripping those prefixes. A session cookie set for HTTPS will not be sent over a later HTTP request.
Fix: Configure one canonical public HTTPS URL for both the frontend and API, forward the public scheme and host, and route all Shisho endpoint prefixes unchanged. Connect the proxy to Shisho over a trusted private network; headers arriving directly from a public-address peer are discarded. Review Deployment and Maintenance and the integration page for the affected route.
OPDS Returns 401
Symptom: An OPDS client rejects the catalog or opens the root catalog but receives 401 Unauthorized on a sub-feed or download.
Likely cause: The client has incorrect Shisho credentials, such as a Device credential paired with another user's username or taken from a Device that isn't an OPDS app, or an HTTP-to-HTTPS redirect caused the client to drop its Basic Authentication header. A 403 Forbidden instead means the credentials worked, but the user's role lacks Books Read or the user cannot access that library.
Verify: Use the exact catalog URL and your Shisho username, with your account password or the credential shown on an OPDS app Device's page. For a 403, check the user's role and library access. Check generated sub-feed links for the wrong scheme and inspect the proxy's X-Forwarded-Proto handling.
Fix: Correct the credentials, or for a 403, the role or library access. Behind an HTTPS-terminating proxy, forward X-Forwarded-Proto: https over a connection Shisho trusts so generated feed links stay on HTTPS. See OPDS Catalog, Deployment and Maintenance, and Users and Permissions.
Kobo Sync or the eReader Browser Cannot Connect
Symptom: Kobo sync cannot reach Shisho, the eReader short URL fails, or a device URL returns the main web interface instead of the device endpoint.
Likely cause: The device cannot resolve or reach the generated host, the reverse proxy does not forward the required path, or the eReader short URL expired before first use.
Verify: From the same network as the device, check that the generated public host is reachable. For Kobo, verify that /kobo/ routes reach Shisho. For the eReader Browser, verify both /e/ short links and /ereader/ full links. Short eReader setup links expire after 30 minutes, while the resulting full URL is the one to bookmark.
Fix: Correct public DNS, scheme, host, and proxy routing. Generate a new eReader short URL if it expired. Do not share a device URL because it contains the device's access key. Follow Kobo Sync or eReader Browser for setup and reset steps.
A Plugin Will Not Load or Run
Symptom: An installed plugin is marked Error or Incompatible, enabling it shows a load error, required configuration is missing, or a scan completes without the expected plugin result.
Likely cause: The plugin requires a newer Shisho version, its manifest or JavaScript failed to load, required configuration is unset, its mode disables automated scans, a per-library override disables it, or the requested access is not declared in its manifest.
Verify: Open Administration > Plugins, select the plugin, and read its status and full load error. Check required configuration, global mode and order, and the library's plugin overrides. For a failure during a job, inspect that job's log; for load-time context, inspect the current-session server logs.
Fix: Update Shisho or the plugin when versions are incompatible, save the required configuration, enable the intended mode, or correct the plugin's manifest and code. Operators should start with Using Plugins. Plugin authors should use Developing Plugins, Manifest and Hooks Reference, and Testing Plugins.