Troubleshooting¶

No dictionaries appear¶

Cause	Fix
The files are not in a dictionary folder	Compare the folders printed at startup, or shown in the folder summary, with where the files are
A file is missing	A StarDict `.dict.dz` needs its `.ifo` and `.idx`; see Formats
The files were added while wudict was running	`☰` → folder summary → `Rescan folders`
Wrong separator in `DICT_DIR` (environment)	`:` on macOS and Linux, `;` on Windows

the dictionaries wudict finds in a folder

wudict list ~/Dictionaries

wudict 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 ~/.wudict/db.

Port 6888 is in use¶

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

for one run

wudict --port 9090

~/.wudict/wudict.toml

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, wudict shows an icon instead of output: on Windows in the notification area (log: %LOCALAPPDATA%\wudict\wudict.log), on macOS in the menu bar (log: ~/Library/Logs/wudict.log).

No sound¶

.mp3, .ogg and .wav play in the browser. Speex (.spx) is converted to WAV first: by the built-in decoder in -cgo builds, by the external speexdec program in -purego builds.

install speexdec

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. wudict 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 first searches are slow, and the CPU is busy¶

wudict is indexing the dictionaries, once each, one at a time, in the background. Indexing one dictionary uses one CPU core. INDEX_WORKERS indexes several at once; AUTO_INDEX = "off" turns indexing off.

Some dictionaries are reported as not searched¶

The search reached SEARCH_MEMORY and did not open the remaining dictionaries that are not indexed. Choose one of them in the picker to search it alone. The limit is off by default on the desktop and on by default on Android.

Wildcard search misses a headword¶

A pattern matches the whole headword: rain finds only rain, *rain* finds every headword that contains rain.
A capital letter or an accent in the pattern does not exclude a headword; it puts the headwords that have it first. With up to 5 results per dictionary, the other spellings can be past the last one: click more… in the section header.
Wildcard matches the headword an entry is filed under, not the other spellings the dictionary lists for it. Exact and prefix find those.
A dictionary that is not indexed yet is not searched; its result section offers to add the headword 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.

from a terminal

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

The Android app shows no dictionaries¶

FOSS build:

No storage access. Settings → Apps → wuDict → Permissions, or Android's All files access list: allow it, then reopen the app.
Wrong folder. The folder is Internal storage → Dictionaries, at the top level, not inside Documents or Download.
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 wudict.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 wudict with --verbose: it logs every request, dictionary open, indexing step and audio conversion.

wudict --verbose

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