ZIM file troubleshooting #681

Optiri · 2026-04-07T23:11:51Z

Optiri
Apr 7, 2026

Over on the discord server some valuable information has been shared on using and troubleshooting zim files on NOMAD. So the info is easier to find I'm adding some of what has been discussed here.
<><><><><><><>

https://discord.com/channels/408879582062575617/1478434975786336266/1487442015783227452

atlwolfRole icon, Verified — 3/28/2026 7:23 AM
I had Claude make an offline guide for fixing the Kiwix crashing issue due to partial downloads. I then had it make a second version optimized for a small LLM. Adding both of these to my Nomad local documentation

Kiwix ZIM File Troubleshooting Guide for Project Nomad

Context for AI Assistant

You are helping a user fix their Kiwix server running inside Docker on a Linux machine as part of Project Nomad. The Kiwix container serves offline ZIM files (like Wikipedia) via a web browser.

System Details

OS: Linux (Debian-based, likely Linux Mint or Ubuntu)
Container runtime: Docker
Kiwix container name: nomad_kiwix_server
Kiwix Docker image: ghcr.io/kiwix/kiwix-serve:3.8.2
Kiwix web URL: http://localhost:8090/
Nomad Command Center URL: http://localhost:8080/
Docker network: project-nomad_default
ZIM file storage path: /opt/project-nomad/storage/zim/
Port mapping: host port 8090 maps to container port 8080

Important Rules

Do NOT add --port=8080 or --address=all to the docker run command. The container image adds these automatically. Adding them causes a "duplicate --port" error and the container exits immediately.
Every time a ZIM file is added or removed, the container must be destroyed and recreated. A simple restart is not enough because the file list is hardcoded at container creation time.
Always include --restart unless-stopped when creating the container so it survives system reboots.

Symptom: http://localhost:8090/ shows "connection refused" or does not load

Step 1: Check if the container is running

Command:

sudo docker ps --format "table {{.Names}}\t{{.Ports}}" | grep kiwix

Possible outcomes:

Outcome A: No output at all
The container is not running. Go to Step 2.

Outcome B: Container name appears but NO port is shown (example: nomad_kiwix_server with blank ports column)
The container is restarting in a crash loop or exited. Go to Step 2.

Outcome C: Container name appears WITH port mapping (example: nomad_kiwix_server 80/tcp, 0.0.0.0:8090->8080/tcp)
The container is running correctly. The problem may be elsewhere (firewall, browser cache). Try opening http://localhost:8090/ in a different browser or run:

curl -v http://localhost:8090/

Step 2: Check if the container exists but is stopped

Command:

sudo docker ps -a | grep kiwix

Possible outcomes:

Outcome A: Container exists with status "Exited" or "Restarting"
Go to Step 3 to find the cause.

Outcome B: No container found at all
Go to Step 6 to create a new container.

Step 3: Find the error in the logs

Command:

sudo docker logs nomad_kiwix_server 2>&1 | grep -i "unable"

Possible outcomes:

Outcome A: Output contains "Unable to add the ZIM file 'FILENAME.zim' to the internal library."
A ZIM file is corrupted or incomplete. Write down the filename. Go to Step 4.

Outcome B: No "unable" message found
Check the first few lines of the log for other errors:

sudo docker logs nomad_kiwix_server 2>&1 | head -10

If you see "Unexpected argument: --port=8080, --port=8080" then the container was created with duplicate --port flags. Go to Step 6 to recreate it correctly.

Step 4: Verify the file is not currently being downloaded

Before deleting any file, check if a process is actively writing to it.

Command (replace PARTIAL_FILENAME with part of the filename, such as wikipedia_en_top1m):

sudo lsof | grep PARTIAL_FILENAME

Possible outcomes:

Outcome A: Output shows lines with w (write mode)
The file is currently being downloaded. To stop the download safely:

sudo docker restart nomad_admin

Wait 10 seconds, then run the lsof command again to confirm the file is no longer being written to. Then go to Step 5.

Outcome B: No output, or only the fuse.gvfsd-fuse warnings appear
The file is not being downloaded. Safe to proceed. Go to Step 5.

Step 5: Delete the bad ZIM file(s)

Command (replace BADFILE.zim with the actual filename from Step 3):

sudo rm /opt/project-nomad/storage/zim/BADFILE.zim

If multiple bad files were identified in Step 3, delete each one.

After deleting, go to Step 6.

Step 6: Recreate the Kiwix container

This must be done every time a ZIM file is added or removed.

Run these commands in order:

sudo docker rm -f nomad_kiwix_server

FILES=$(ls /opt/project-nomad/storage/zim/*.zim | xargs -I {} basename {})

sudo docker run -d \
  --name nomad_kiwix_server \
  --network project-nomad_default \
  --restart unless-stopped \
  -p 8090:8080 \
  -v /opt/project-nomad/storage/zim:/data \
  ghcr.io/kiwix/kiwix-serve:3.8.2 \
  $FILES

After running these commands, go to Step 7.

Step 7: Verify the fix

Run both of these commands:

sudo docker ps --format "table {{.Names}}\t{{.Ports}}" | grep kiwix

sudo docker logs nomad_kiwix_server 2>&1 | grep -i "unable"

Possible outcomes:

Outcome A: Port mapping is shown AND no "unable" errors
The fix is complete. Open http://localhost:8090/ in a browser to confirm.

Outcome B: No port mapping shown OR "unable" errors found
Another bad ZIM file exists. Go back to Step 3 and repeat the process.

Symptom: Kiwix was working but stopped after a system reboot

The container may have lost its restart policy or was replaced.

Command:

sudo docker start nomad_kiwix_server

If this succeeds, ensure it persists across future reboots:

sudo docker update --restart unless-stopped nomad_kiwix_server

If docker start fails, go to Step 2 in the main troubleshooting flow above.

Symptom: Kiwix was working but stopped after adding a new ZIM file

The container does not automatically detect new files. You must recreate it.

Go to Step 6 above to recreate the container with the updated file list.

Symptom: Kiwix was working but stopped after deleting a ZIM file

The container is trying to serve a file that no longer exists. It will crash.

Go to Step 6 above to recreate the container with the updated file list.

How to check if a ZIM file is complete or corrupted

Check local file size

ls -lh /opt/project-nomad/storage/zim/FILENAME.zim

Look up expected file size online

Visit any of these mirror sites and find the matching filename:

Compare sizes

If the local file is significantly smaller than the listed size on the mirror site, the file is incomplete and should be deleted and re-downloaded.

Common examples of expected sizes (approximate)

wikipedia_en_all_maxi = 110-120 GB (full English Wikipedia with images)
wikipedia_en_top1m_maxi = 43-45 GB (top 1 million articles with images)
wikipedia_en_wp1-0.8_maxi = 7.5-8 GB (Wikipedia Version 0.8 curated articles)
wikipedia_en_top_maxi = 7.5-8 GB (top ~50,000 articles with images)
wikipedia_en_100_mini = small, under 100 MB

Quick isolation test: verify Kiwix works with one small file

If you cannot determine which file is causing problems, test with a known good small file:

sudo docker rm -f nomad_kiwix_server
sudo docker run -d \
  --name nomad_kiwix_test \
  --network project-nomad_default \
  -p 8090:8080 \
  -v /opt/project-nomad/storage/zim:/data \
  ghcr.io/kiwix/kiwix-serve:3.8.2 \
  wikipedia_en_100_mini_2025-06.zim

Check if it works:

sudo docker ps --format "table {{.Names}}\t{{.Ports}}" | grep kiwix

If port 8090 is mapped and http://localhost:8090/ loads, the Kiwix setup is fine and the problem is one or more bad ZIM files. Clean up the test:

sudo docker rm -f nomad_kiwix_test

Then use the main troubleshooting flow to find and remove the bad file(s).

How to re-download a ZIM file safely

Using aria2c (fast, multi-connection)

sudo apt install aria2
sudo aria2c -x 16 -s 16 -c -d /opt/project-nomad/storage/zim/ "DOWNLOAD_URL"

The -c flag enables resume if interrupted. The -x 16 -s 16 uses 16 parallel connections.

Using wget (simple, resumable)

sudo wget -c -P /opt/project-nomad/storage/zim/ "DOWNLOAD_URL"

The -c flag enables resume if interrupted.

Mirror URLs for ZIM files

Replace FILENAME.zim with the actual file name:

https://download.kiwix.org/zim/wikipedia/FILENAME.zim
https://ftp.fau.de/kiwix/zim/wikipedia/FILENAME.zim
https://dumps.wikimedia.org/other/kiwix/zim/wikipedia/FILENAME.zim
https://www.mirrorservice.org/sites/download.kiwix.org/zim/wikipedia/FILENAME.zim

After downloading, recreate the container using Step 6.

Summary of key commands

Task	Command
Check if kiwix is running	`sudo docker ps --format "table {{.Names}}\t{{.Ports}}" \| grep kiwix`
Check for bad ZIM files	`sudo docker logs nomad_kiwix_server 2>&1 \| grep -i "unable"`
Check if file is being downloaded	`sudo lsof \| grep PARTIAL_FILENAME`
Stop an active download	`sudo docker restart nomad_admin`
Delete a bad file	`sudo rm /opt/project-nomad/storage/zim/BADFILE.zim`
Recreate kiwix container	See Step 6 (three commands in sequence)
Start kiwix after reboot	`sudo docker start nomad_kiwix_server`
Make kiwix survive reboots	`sudo docker update --restart unless-stopped nomad_kiwix_server`
List all ZIM files	`ls -lh /opt/project-nomad/storage/zim/*.zim`
Monitor a download in progress	`watch -n 10 ls -lh /opt/project-nomad/storage/zim/FILENAME.zim`

kiwix-troubleshooting-guide-for-llm.md

<><><><><><>

Fixing Kiwix ZIM File Errors in Project Nomad

The Problem

When a ZIM file in /opt/project-nomad/storage/zim/ is corrupted or incomplete, the nomad_kiwix_server container will crash or exit immediately. The Kiwix web interface at http://localhost:8090/ will show "connection refused."

Step 1: Find the Bad File

Run this to check the kiwix container logs for errors:

sudo docker logs nomad_kiwix_server 2>&1 | grep -i "unable"

This will show something like:

Unable to add the ZIM file 'FILENAME.zim' to the internal library.

Write down the filename(s).

Step 2: Check If the File Is Being Downloaded

Before deleting anything, make sure nothing is actively writing to the file:

sudo lsof | grep FILENAME

Replace FILENAME with part of the bad file's name (e.g., wikipedia_en_top1m).

If you see output with w (write) — the file is still downloading. Either wait for it to finish or stop the download first by restarting the admin container:

sudo docker restart nomad_admin

Then run the lsof command again to confirm it's no longer being written to.

If no output — safe to delete.

Step 3: Delete the Bad File(s)

sudo rm /opt/project-nomad/storage/zim/BADFILE.zim

Repeat for each bad file found in Step 1.

Step 4: Recreate the Kiwix Container

The container has a hardcoded list of ZIM files from when it was created. After adding or removing any ZIM file, you must recreate it.

sudo docker rm -f nomad_kiwix_server
FILES=$(ls /opt/project-nomad/storage/zim/*.zim | xargs -I {} basename {})
sudo docker run -d \
  --name nomad_kiwix_server \
  --network project-nomad_default \
  --restart unless-stopped \
  -p 8090:8080 \
  -v /opt/project-nomad/storage/zim:/data \
  ghcr.io/kiwix/kiwix-serve:3.8.2 \
  $FILES

Step 5: Verify It's Working

Check the container is running with port mapped:

sudo docker ps --format "table {{.Names}}\t{{.Ports}}" | grep kiwix

You should see:

nomad_kiwix_server     80/tcp, 0.0.0.0:8090->8080/tcp, [::]:8090->8080/tcp

Check for any remaining errors:

sudo docker logs nomad_kiwix_server 2>&1 | grep -i "unable"

If no output, kiwix is clean. Open http://localhost:8090/ in your browser.

Step 6: If the Container Still Shows No Port

If docker ps shows the container name but no port, it exited. Check why:

sudo docker logs nomad_kiwix_server 2>&1 | head -5

Look for another "Unable to add" error and repeat from Step 1.

Quick Test: Verify a Single File Works

If you can't figure out which file is bad, test with one known good small file:

sudo docker rm -f nomad_kiwix_server
sudo docker run -d \
  --name nomad_kiwix_test \
  --network project-nomad_default \
  -p 8090:8080 \
  -v /opt/project-nomad/storage/zim:/data \
  ghcr.io/kiwix/kiwix-serve:3.8.2 \
  wikipedia_en_100_mini_2025-06.zim

If http://localhost:8090/ works, the problem is definitely a bad ZIM file. Remove the test container and use binary search (add files in batches) to find the culprit.

sudo docker rm -f nomad_kiwix_test

How to Check If a ZIM File Is Complete

Look up the expected file size at:

Compare with your local file:

ls -lh /opt/project-nomad/storage/zim/FILENAME.zim

If your file is significantly smaller than the listed size, it's incomplete.

Notes

Every time you add or remove a ZIM file, you must recreate the container (Step 4)
The --restart unless-stopped flag ensures the container survives reboots
The container image is ghcr.io/kiwix/kiwix-serve:3.8.2 — do not add --port=8080 or --address=all to the command as the image adds these automatically
ZIM files go in /opt/project-nomad/storage/zim/
Kiwix serves on http://localhost:8090/
Nomad Command Center is at http://localhost:8080/

kiwix-fix-guide.md

How to Download Large ZIM Files Faster

The File

URL: https://wi.mirror.driftle.ss/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim
Size: ~116 GB
Contents: Full English Wikipedia with all articles and images

Method 1: aria2c (Fastest — uses multiple parallel connections)

Install

Linux:

sudo apt install aria2

Windows:
Download from https://github.com/aria2/aria2/releases (grab the win-64bit zip, extract it)

Download

Linux:

aria2c -x 16 -s 16 -c "https://wi.mirror.driftle.ss/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim"

Windows (Command Prompt or PowerShell):

aria2c.exe -x 16 -s 16 -c "https://wi.mirror.driftle.ss/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim"

What the flags mean

-x 16 — use 16 connections to the server simultaneously
-s 16 — split the file into 16 segments
-c — resume if interrupted (safe to Ctrl+C and restart the same command)

To save to a specific folder

Linux:

aria2c -x 16 -s 16 -c -d /opt/project-nomad/storage/zim/ "https://wi.mirror.driftle.ss/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim"

Windows:

aria2c.exe -x 16 -s 16 -c -d "D:\Downloads" "https://wi.mirror.driftle.ss/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim"

Method 2: wget (Simpler, single connection, resumable)

wget -c "https://wi.mirror.driftle.ss/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim"

Slower than aria2c since it only uses one connection, but -c allows resume if interrupted.

Method 3: Windows GUI Download Managers

Internet Download Manager (IDM) — paid, very fast, auto-splits into multiple connections
JDownloader — free, supports multi-connection downloads
Free Download Manager — free, supports multi-connection downloads

Paste the URL into any of these and they will handle the rest.

Alternative Mirrors (if the above URL is slow, try these)

https://download.kiwix.org/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim
https://ftp.fau.de/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim
https://dumps.wikimedia.org/other/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim
https://www.mirrorservice.org/sites/download.kiwix.org/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim

With aria2c you can even try multiple mirrors at once:

aria2c -x 16 -s 16 -c \
  "https://wi.mirror.driftle.ss/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim" \
  "https://ftp.fau.de/kiwix/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim" \
  "https://download.kiwix.org/zim/wikipedia/wikipedia_en_all_maxi_2026-02.zim"

This pulls chunks from all three servers simultaneously for maximum speed.

After Downloading

If you downloaded on Windows, copy the file to the Linux machine via SMB:

sudo mount -t cifs //WINDOWS_IP/ShareName /mnt/winshare -o username=yourusername
sudo rsync --progress /mnt/winshare/wikipedia_en_all_maxi_2026-02.zim /opt/project-nomad/storage/zim/
sudo umount /mnt/winshare

Then recreate the Kiwix container to pick up the new file:

sudo docker rm -f nomad_kiwix_server
FILES=$(ls /opt/project-nomad/storage/zim/*.zim | xargs -I {} basename {})
sudo docker run -d \
  --name nomad_kiwix_server \
  --network project-nomad_default \
  --restart unless-stopped \
  -p 8090:8080 \
  -v /opt/project-nomad/storage/zim:/data \
  ghcr.io/kiwix/kiwix-serve:3.8.2 \
  $FILES

fast-zim-download-guide.md

---

To add your own zim files to NOMAD and have them show up in the kiwix app, do the following:

https://discord.com/channels/408879582062575617/1487948892380336329/1487966756294361250

Run the command:

sudo docker stop nomad_kiwix_server

Copying the zim file(s) to the: /opt/project-nomad/storage/zim folder

Then run the command:

sudo docker rm -f nomad_kiwix_server
FILES=$(ls /opt/project-nomad/storage/zim/*.zim | xargs -I {} basename {})
sudo docker run -d \
  --name nomad_kiwix_server \
  --network project-nomad_default \
  --restart unless-stopped \
  -p 8090:8080 \
  -v /opt/project-nomad/storage/zim:/data \
  ghcr.io/kiwix/kiwix-serve:3.8.2 \
  $FILES

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ZIM file troubleshooting #681

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

ZIM file troubleshooting #681

Uh oh!

Uh oh!

Optiri Apr 7, 2026

Kiwix ZIM File Troubleshooting Guide for Project Nomad

Context for AI Assistant

System Details

Important Rules

Symptom: http://localhost:8090/ shows "connection refused" or does not load

Step 1: Check if the container is running

Possible outcomes:

Step 2: Check if the container exists but is stopped

Possible outcomes:

Step 3: Find the error in the logs

Possible outcomes:

Step 4: Verify the file is not currently being downloaded

Possible outcomes:

Step 5: Delete the bad ZIM file(s)

Step 6: Recreate the Kiwix container

Step 7: Verify the fix

Possible outcomes:

Symptom: Kiwix was working but stopped after a system reboot

Symptom: Kiwix was working but stopped after adding a new ZIM file

Symptom: Kiwix was working but stopped after deleting a ZIM file

How to check if a ZIM file is complete or corrupted

Check local file size

Look up expected file size online

Compare sizes

Common examples of expected sizes (approximate)

Quick isolation test: verify Kiwix works with one small file

How to re-download a ZIM file safely

Using aria2c (fast, multi-connection)

Using wget (simple, resumable)

Mirror URLs for ZIM files

Summary of key commands

Fixing Kiwix ZIM File Errors in Project Nomad

The Problem

Step 1: Find the Bad File

Step 2: Check If the File Is Being Downloaded

Step 3: Delete the Bad File(s)

Step 4: Recreate the Kiwix Container

Step 5: Verify It's Working

Step 6: If the Container Still Shows No Port

Quick Test: Verify a Single File Works

How to Check If a ZIM File Is Complete

Notes

How to Download Large ZIM Files Faster

The File

Method 1: aria2c (Fastest — uses multiple parallel connections)

Install

Download

What the flags mean

To save to a specific folder

Method 2: wget (Simpler, single connection, resumable)

Method 3: Windows GUI Download Managers

Alternative Mirrors (if the above URL is slow, try these)

After Downloading

To add your own zim files to NOMAD and have them show up in the kiwix app, do the following:

Replies: 0 comments

Optiri
Apr 7, 2026