How to Troubleshoot BeeRef When It Won't Start

Updated

If BeeRef won't start, the first thing to check is its log file. When the app is running, you can open the log from Help -> Show Debug Log. If BeeRef doesn't start at all, you can't reach that menu, so you need to open the log file directly from your system:

  • Windows: C:\Documents and Settings\USERNAME\Application Data\BeeRef\BeeRef.log
  • Linux and macOS: /home/USERNAME/.config/BeeRef/BeeRef.log

Replace USERNAME with your actual user name. The log records what BeeRef did before it stopped, which is usually enough to tell whether the problem is a missing file, a permissions issue, or something in your system setup.

Reading the log

Open the file in any text editor. You are looking for the last lines before the app stopped, since those describe the step it failed on. Errors about missing libraries, unreadable files, or failed writes point to different fixes:

  • A missing or unreadable file usually means the BeeRef download is incomplete or was moved after installation.
  • A permissions error on Linux or macOS often means the executable bit was never set, or the app can't write to its config directory.
  • A library or dependency error suggests the build doesn't match your system (see the Linux note below).

Common causes and what to check

Linux: the file isn't executable

BeeRef's Linux builds are distributed as files that need executable rights before they will run. If you skipped that step, the app simply won't launch. Set the permission, then try again.

Also note that the different Linux versions are built on different Ubuntu releases. They should work on other distributions, but you may have to try more than one build to find the one that runs on your system.

macOS: the app is blocked from running

macOS users who have trouble running BeeRef should follow the detailed instructions linked from the BeeRef site for their situation. This is the usual cause when the log is empty or the app never gets far enough to write one.

The log file doesn't exist

If there is no log at the path above, BeeRef likely never reached the point of creating its config directory. In that case, re-download the file for your operating system from the latest release and start from a clean copy.

A note on the .bee file format

If BeeRef starts but a specific .bee file won't open, the problem is in the file rather than the app. A .bee file is a SQLite database with the images stored in an sqlar table, so you can inspect or extract it independently of BeeRef:

sqlite3 myfile.bee -Axv

This works even if BeeRef itself is misbehaving, and it's a useful way to confirm whether the file is intact.

If the log doesn't explain it

Work through the basics in order: confirm you downloaded the build for your operating system, confirm the file has executable rights on Linux, and confirm the app can write to its config directory. If BeeRef still won't start, the log output is the detail to share when asking for help, since it shows exactly where startup stopped.