Kiwix - Troubleshooting
Skip to content
www.kiwix.org
pro.kiwix.org
hub.kiwix.org
Our non-profit roots
www.kiwix.org
Our mainstream solutions
Custom solutions and services
pro.kiwix.org
Our community hub
hub.kiwix.org
KIWIX
Donate
KIWIX
Donate
Troubleshooting
Troubleshooting
WikiWanderer
2026-03-03T12:24:25+00:00
Select the issue you are having from the list below.
If you are having an issue that you have not found the answer to below, please contact us at
hello@kiwix.org
, detailing the problem.
All
Content Bundles
Imager Service
Kiwix Hotspot
Reader
Standard Setup Procedure
renaud gaudin
2026-03-03T12:38:29+00:00
Standard Setup Procedure
Here’s the standard testing procedure to ensure that your hardware and tools are OK. If none of these work, please drop us a note and we’ll run some more tests to try and get to the bottom of it.
Downloading and flashing the image file
Did you download the image via regular HTTP download or via torrent? We
highly
recommend the latter as it checks again file corruption. Also make sure to use
Transmission
(4.11+) or another webseed client so it does not wait uselessly for other peers before starting to download;
When flashing your image onto the microSD card with the
Raspberry Pi imager
, let it go through the full verification step so as to make sure the image is copied correctly;
Do not change any of the settings (network name or whatnot) as it bricks the system;
If your card isn’t new then maybe try with another one. These things are pretty fragile and tend to wear off over time, might be worth checking out. See also below for hardware testing.
Running the Raspberry Pi
Remember: the Raspberry Pi zero 2W is not supported yet.
You need to give it 5-8 minutes for the first boot to unpack everything and show a network; after that it’ll be much smoother;
Check your hardware
Download the Free Image from the
Content Bundles Page
. It’s a smaller download that speeds up testing. Please
use the torrent link
to ensure there is no issue with the download (it downloads from the same HTTPs location but it ensures it’s not corrupt).
Insert your SD-card onto your computer.
Launch the
Raspberry Pi Imager software
Don’t use the Choose device button
Select the downloaded image file via
Choose OS -> Use custom
(filename should be
demo_yyyy-mm_xxxxxxxx.img
or similar)
Select the SD-card using
Choose storage
button
Click
Next
button
Select
No
when asked about
OS customisation
Select
Yes
at the warning to confirm your SD-card will be erased
Let the process complete, including the verification part
At this point the SD card should contain exactly what it’s supposed to.
Insert the card in the Pi.
Make sure the power supply is appropriate:
12.5W (2.5A) for Pi Zero2W, Pi3B and Pi 3B+.
Pi3B accepts 2.1A but we recommend the more common 2.5A.
15W (3A) for Pi 4 and Pi 400
27W (5A) for Pi 5.
Plug the power cord, lights should turn on.
Wait 15 good minutes (to be safe), so 900 seconds.
Using another device, look for an SSID named “Kiwix Hotspot”. It’s an open network and it is not providing Internet access so depending on your testing system, it may not be a suggested SSID.
WiFi network not showing up (Kiwix Hardware)
renaud gaudin
2026-03-03T12:38:48+00:00
WiFi network not showing up (Kiwix Hardware)
Every single Kiwix Hotspot (Kiwix hardware) is manually tested before shipping, including its power-plug. This eliminates all risks associated with download, flashing, hardware defect, etc. That and the fact that we are using Solid State Drive instead of microSD card makes out-of-box issues very unlikely.
After a full year of shipping devices, the single issue we had was a defective power-plug that had us include power-plug testing in our process.
If you can’t see the WiFi network, please check first with a different phone or computer. Since December 2025, the default WiFi network use WiFi AC (also called WiFi5) over a 5Ghz frequency. That’s widely supported but some old or very low-end devices might only support 2.4Ghz networks.
If you’re confident you’ve tested with different devices that support 5Ghz,
, ideally with your serial number (found under the device). There remains a slight chance that the device or the power plug has been damaged during shipping.
WiFi network not showing up (OS-only)
renaud gaudin
2026-03-03T12:39:03+00:00
WiFi network not showing up (OS-only)
After setting up your device for the first time, a non-visible WiFi network is a sign of a problem but it doesn’t tell which one. The counterpart is that if you see the WiFi network, your Hotspot is working!
First of all, check with another device. Since version 2025-12, the default WiFi network use WiFi AC (also called WiFi5) over a 5Ghz frequency. That’s widely supported but some old or very low-end devices might only support 2.4Ghz networks.
If it wasn’t the issue,
check and redo
the
Standard Setup Procedure
. Each step is important! Don’t overlook any.
Downloads over HTTP might appear successful but be corrupt. Torrent will ensure it’s not corrupt.
Not adding the customisation from Raspberry-Pi Imager is mandatory. As the tool records those as settings, you may have to clear them.
Using a good-quality, in good condition (that usually means new) microSD card is decisive.
Using the verification step of the flashing process is required. It ensures the exact content written to the microSD card could be read. A failure here would indicate the new to replace the microSD card. A success cannot 100% eliminate a microSD card issue though as only the written blocks are tested.
Using the correct power-plug is also mandatory. An underrated power plug or a defective one (that’s more frequent than you think!) would likely boot up the Pi but wreck havoc upon startup.
Make sure the microSD card is inserted in the Pi. We’ve all forgot it at some point 😅.
If you’ve checked all this and could not fix the issue, please contact us so we can diagnose together. If you can, please plug your Pi to a monitor and include screenshots or a screen-cast of the booting screen so we can identify error messages and clues.
Download speed is very slow
renaud gaudin
2026-03-03T12:26:15+00:00
Download speed is very slow
Downloading a Content Bundle or Imager-service made image can be very slow. You should expect fluctuating speeds given the very large size of our images.
Constant very slow speeds are not to be expected and can turn your purchase into a very frustrating experience.
Our images are hosted by
Wasabi
and there is no throttling involved. If you are confident the problem is not on your end of the connection, contact us so we can check and potentially report to Wasabi: we’ve had multiple cases of inexplicably slow downloads and are trying to document them.
Unable to access the dashboard
renaud gaudin
2026-03-03T14:17:59+00:00
Unable to access the dashboard
You are connected to the Hotspot’s WiFi network but didn’t get the Captive Portal and can’t access the Hotspot dashboard (
)?
Check that you have no VPN software running as by nature those prevent direct connections and the out-server of your VPN provider surely has no access to your physical Hotspot.
If you are an Apple/iCloud+ User, mind that
Icloud Private Relay
is a VPN and must be disabled to access the Hotpost as well.
Cannot copy ZIM files on my hard drive, USB disk or SD card.
WikiWanderer
2026-03-03T12:37:18+00:00
Cannot copy ZIM files on my hard drive, USB disk or SD card.
Storage is often formatted using the
FAT32
filesystem which can’t store files larger than 4GB.
We recommend to use
exFAT
or even
NTFS
which can deal with large files and are broadly supported.
Your issues remain unsolved?
Please detail in full the issue(s) you need help with and we’ll get back to you as soon as we can. If you have a more general query, please view our
FAQ
before contacting us.
Bridging the digital
divide a little more
each day.
Donate
Signup to our newsletter
Join the Offline revolution! Receive updates, resources and inspiration directly to your inbox.
hello@kiwix.org
Headquarters
Kiwix Association
Avenue Auguste-Tissot 4
1006 Lausanne
Switzerland
useful links
Kiwix World
CC-BY-SA
Association Kiwix —
Terms & Conditions
— Hosting supported by
raidboxes.io
Page load link
Be in the know about all things Offline.
Subscribe to our newsletter
Join the Offline knowledge revolution—updates, resources and inspiration from Kiwix delivered directly to you.
Go to Top