Troubleshooting¶

No dictionaries appear¶

dictshelf list ~/Dictionaries

DictShelf does not start: DICT_DIR and DB_DIR are the same folder¶

The library (DB_DIR) must be a different folder from every dictionary folder. Usually only DICT_DIR needs setting; the library defaults to ~/.dmshlabs/dictshelf/db.

Port 6888 is in use¶

Another program uses the port; startup reports it. Choose another port:

dictshelf --port 9090

SERVER_PORT = "9090"

Then open localhost:9090.

No browser tab opens¶

Open localhost:6888. A tab is not opened when NO_BROWSER is set.

Started without a console, DictShelf shows an icon instead of output: on Windows in the notification area (log: %USERPROFILE%\.dmshlabs\dictshelf\db.logs\dictshelf.log), on macOS in the menu bar (log: ~/Library/Logs/DMSH Labs/DictShelf/dictshelf.log).

No sound¶

.mp3, .ogg and .wav play in the browser. Speex (.spx) is converted to WAV first, by the decoder compiled into the binary. With SPEEX_BACKEND set to external the speexdec program is used instead, and a missing one is reported when the server starts.

brew install speex     # macOS
apt install speex      # Debian, Ubuntu

SPEEXDEC (--speexdec) sets its path. Startup prints the decoder in use, or how to install one.

A .spx file in a res/ folder is not converted: use .mp3 or .wav there.

An article is broken, or its buttons do nothing¶

A dictionary's stylesheet or script is damaged or missing. DictShelf logs a warning when it serves a text resource that contains NUL bytes, with the res/ path that would override it. A ⚠ in the dictionary's result header marks a script error.

Resource overrides

An image or sound is missing¶

In the browser's network panel, find the failing request to /res/<dictionary id>/<path>. A 404 means the dictionary lacks the file; <path> is where a resource override goes.

The CPU is busy indexing dictionaries¶

DictShelf indexes new dictionaries in the background. The number of concurrent dictionaries is calculated from the machine's logical processors, leaving one processor for other work when possible and sharing preparation workers across dictionaries. Search does not start an index job.

A dictionary says its index is not ready¶

Every dictionary is searched through its index, and a dictionary without one is not searched at all — its row says the index is not ready and keeps saying so while it is prepared in the background. Nothing is wrong with the dictionary file: the library rebuilds a missing index by itself (after the folder was deleted from outside, for instance), and the row answers as soon as the build finishes. To rebuild now, use the dictionary's index switches in the panel.

Contains search misses a headword¶

• Contains matches the query as a literal substring, ignoring case and accents; it does not correct spelling.
• The contains index is outdated: its switch in the dictionary panel says so. Click it to rebuild the index.

The library uses too much disk space¶

The dictionary panel shows each index's size; click a switch to remove that index. Rescan folders lists orphans, library folders whose dictionary files are gone, and deletes the ones you tick.

dictshelf clean              # list broken library folders and orphans
dictshelf clean -f           # delete the broken ones
dictshelf clean -f -orphans  # and the orphans

The Android app shows no dictionaries¶

FOSS build:

1. No storage access. Settings → Apps → DictShelf → Permissions, or Android's All files access list: allow it, then reopen the app.
2. Wrong folder. The folder is Internal storage → Dictionaries, at the top level, not inside Documents or Download.
3. Files added while the app was open. ☰ → folder summary → Rescan folders.

Google Play build: dictionaries must be imported; see Add dictionaries.

The Android app while it is not on screen¶

When the app is not visible, the server starts no new indexing and closes the dictionaries it can reopen. Indexed dictionaries stay open. Indexing, downloads and rebuilds already running continue in a foreground service, with a progress notification. See Android app.

A change to dictshelf.toml has no effect¶

A command-line flag or an environment variable sets the same key and takes precedence. The setup page and /api/config show where each value comes from.

Priority

Anything else¶

Start DictShelf with --verbose: it logs every request, dictionary open, indexing step and audio conversion.

dictshelf --verbose

Open an issue with that output and the output of dictshelf --version.