Troubleshooting

▶️ If you need help or have a question, you can open an issue or reach out on Twitter.

What are you having an issue with?:

Installing

Make sure you’ve followed the Manual Setup guide in the [[Install]] instructions first. Then check here for help depending on what component you need help with:

Python

Make sure you have at least Python 3.9 installed on your system.

python3 --version
pip install --upgrade pip setuptools

If you still need help getting Python installed, the official Python docs are a good place to start.

Chromium/Google Chrome

For more info, see the [[Chromium Install]] page.

ArchiveBox depends on being able to access a chromium-browser/google-chrome executable. The executable used defaults to chromium-browser but can be manually specified with the environment variable CHROME_BINARY:

env CHROME_BINARY=/usr/local/bin/chromium-browser archivebox add ~/Downloads/bookmarks_export.html

  1. Test to make sure you have Chrome on your $PATH with:

which chromium-browser || which google-chrome

If no executable is displayed, follow the setup instructions to install and link one of them.

  1. If a path is displayed, the next step is to check that it’s runnable:

chromium-browser --version || google-chrome --version

If no version is displayed, try the setup instructions again, or confirm that you have permission to access chrome.

  1. If a version is displayed and it’s <59, upgrade it:

apt upgrade chromium-browser -y
# OR
brew cask upgrade chromium-browser

  1. If a version is displayed and it’s >=59, make sure ArchiveBox is running the right one:

env CHROME_BINARY=/path/from/step/1/chromium-browser archivebox version   # replace the path with the one you got from step 1

Wget & Curl

If you’re missing wget or curl, simply install them using apt or your package manager of choice. See the “Manual Setup” instructions for more details.

If wget times out or randomly fails to download some sites that you have confirmed are online, upgrade wget to the most recent version with brew upgrade wget or apt upgrade wget. There is a bug in versions <=1.19.1_1 that caused wget to fail for perfectly valid sites.

Archiving

Lots of skipped sites

If you ran the archiver once, it wont re-download sites subsequent times, it will only download new links. If you haven’t already run it, make sure you have a working internet connection and that the parsed URLs look correct. You can check the ArchiveBox stdout logs or the Web UI to see what links it’s downloading.

If you’re still having issues, try deleting or moving the ./archive folder (back it up first!) and running archivebox init again.

Lots of errors

Make sure you have all the dependencies installed and that you’re able to visit the links from your browser normally. Open an issue with a description of the errors if you’re still having problems.

Hosting the Archive

If you’re having issues trying to host the archive via nginx, make sure you already have nginx running with SSL. If you don’t, google around, there are plenty of tutorials to help get that set up. Open an issue if you have problem with a particular nginx config.

Other database or filesystem issues

See here for more info:

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Upgrading-or-Merging-Archives

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Upgrading-or-Merging-Archives#database-troubleshooting

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Upgrading-or-Merging-Archives#repairing-a-corrupted-database

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Upgrading-or-Merging-Archives#modify-the-archivebox-sqlite3-db-directly

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Upgrading-or-Merging-Archives#merge-two-or-more-existing-archives

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Usage#python-shell-usage

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Usage#sql-shell-usage

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Security-Overview#do-not-run-as-root

  • https://github.com/ArchiveBox/ArchiveBox/wiki/Security-Overview#output-folder