Troubleshooting
Common problems and what to check.
Thumbnails look low quality
The standalone binary falls back to the built-in GD library, which produces lower-quality thumbnails and supports fewer formats. Install ImageMagick and librsvg on the build host for better output, or use the Docker image, which bundles them. See Images.
The search box does nothing
Search is client-side, built into Wikven via SifterSearch and on by default. If the box does not respond, search was turned off (an empty SifterSearchOutputDir), or its bundle path does not match where the site is served (set SifterSearchBundlePath for a subdirectory deploy). See Searching.
A page is missing from the site
The build aborts if any page fails to import, printing Failed to import N page(s) with the file names. A common cause is a file whose name does not map to a valid title; rename it (the build warns when a name does not round-trip). Re-run the build and read the log for the failing file.
Fetching fails over HTTPS
Fetching Wikimedia Commons images and third-party extensions or skins needs your system's CA certificates. On a minimal host without them (common with the standalone binary), install your distribution's CA bundle, for example the ca-certificates package. A site with only local content and images needs no network access.
The binary will not run on macOS or Windows
The standalone binary is Linux-only (x86_64 and arm64). On macOS or Windows, use the Docker image instead. See Installation.
A setting in .wikven.yaml does nothing
Read the build log first: it warns about the mistakes it can see. unknown config means a name nothing loaded here defines — a typo, most often, since a name nobody owns is otherwise applied and ignored; the warning names the closest setting it does know of. It waits until every extension and skin your site lists is installed, because a setting can belong to any of them. unknown top-level key means a setting outside config, extensions or skins. A URL template warning means WikvenEditUrl and friends are missing their $1.
A silent one to check by eye: a config value replaces the default rather than merging with it, so a list or map you set has to carry every entry you want, including the ones you were happy with. See Configuration.
An extension or skin was not loaded
nothing provides extension 'X', or the same for a skin, means the name in your extensions or skins list was not found on disk, and the build stopped rather than publish a site without it. Either it is misspelled, or it is not one of the components Wikven ships and needs a source under the WikvenRepositories map. See Extensions.
Two configuration files, one of them ignored
multiple site config files present means your source directory holds more than one of the accepted names. The first in precedence order wins and the rest are ignored; delete the ones you do not want, rather than editing a file the build is not reading.
Every page says it was edited on the same day
Page dates come from the commit that last changed each source file, and a shallow clone holds only one commit. Build from a full one: clone without --depth, or deepen the clone you have with git fetch --unshallow. On GitHub Actions that is fetch-depth: 0, as the workflow in Deploying does. Building from a directory that is not a repository at all has the same effect, and neither case fails the build: the log says it happened, and every page is dated at the commit being built.
The build fails on a Wikimedia Commons image
Every parse of a page embedding a Commons image asks Commons for its thumbnail. Wikven retries a failed lookup twice before giving up, and then names the image it could not resolve and stops, rather than publishing a page with a hole in it. Check the file name is right and still exists on Commons, and that the build host can reach the network — see also Fetching fails over HTTPS above.
A skin's pass failed
On a site with several skins, each is rendered by its own process and the build reports each one that failed by name (build failed for skin ...). The output of each pass is printed under its own heading, so read the section for the named skin rather than the end of the log. If the machine is short of memory, WIKVEN_BUILD_JOBS=1 runs the passes one at a time; see Commands.