Troubleshooting
Start with benchbar doctor. It is read only, every warning and failure
names its fix, and benchbar repair applies the fixes it flagged. The
full command output of every mutating run is in
logs/<date>-<time>-<pid>.log of benchbar’s state folder, and the backups of
every replaced file in backups/<date>-<time>-<pid>/. The state folder is
~/.local/state/benchbar with Homebrew, the one line installer and the
CLI inside BenchBar.app, or .benchbar in the folder you cloned;
benchbar where shows it.
On Linux and Windows, see Install: Linux and Windows and WSL below.
Common stumbles
benchup: command not found. Run source ~/.zshrc once, or open a
new Terminal tab.
benchstatus says stop flag crash. The bench crashed three times in
ten minutes and paused itself. benchlogs shows why, and --previous
shows the run before. Fix the cause, then benchup.
benchstatus says stop flag port_conflict. When the runner
started, a process that is not this bench’s held one of its ports, so it
paused instead of starting. benchbar doctor names the process. Free
the port, or give the bench its own ports with benchbar ports setup,
then benchup.
The site loads without styling. Run benchbar doctor. If the built
assets are missing, benchbar repair runs bench build.
bench: command not found after phase 2. benchbar installs bench
with uv, or with pipx when uv is missing; both put it in ~/.local/bin.
Run uv tool update-shell (or pipx ensurepath) and open a new
Terminal.
The browser cannot connect to macdev. The site’s line in
/etc/hosts, which points the name at your own Mac, is missing. Run
benchbar site hosts: it adds a 127.0.0.1 line for every site of the
bench inside benchbar’s marked block, after one sudo prompt, and backs
the file up first. benchbar repair does the same for the default site.
Editing /etc/hosts by hand works too, but keep a copy first
(sudo cp /etc/hosts /etc/hosts.bak) and use your site’s name in place
of macdev.
MariaDB rejects the root password. benchbar mariadb-password prints
the one in the Keychain; confirm it with mariadb -u root -p in another
tab. If it changed, run MARIADB_ROOT_PASSWORD='...' benchbar install
once to verify and save the new one. Forgotten entirely: see
resetting the MariaDB root password
below.
Phase 00 stops: “MariaDB root already has a password”. A bench set
up before 0.3 never stored the root password in the Keychain. Type it when
asked (it is verified and saved), or pass MARIADB_ROOT_PASSWORD. If
nobody knows it, follow
resetting the MariaDB root password.
bench init fails with “Operation not permitted” on crontab. On
macOS 14 and later a Terminal without Full Disk Access may not write a
crontab, and bench then offers to delete the new bench (frappe/bench#1730,
open). benchbar runs bench init --no-backups, which needs no crontab,
and doctor’s full_disk_access check says when the Terminal lacks it. To
use bench setup backups later: System Settings > Privacy & Security >
Full Disk Access, add Terminal, open a new window.
Two benches, and one crashes when the other starts. Both benches need
runner template v3 (0.4): an older runner clears every socketio.js on
the Mac when its bench starts. benchbar doctor on each bench says
“runner is outdated” until benchbar repair --bench-dir ... rewrites it.
A v16 bench and MariaDB 10.11. Frappe v16 accepts MariaDB 10.6 to
11.8, so a v16 bench shares the mariadb@10.11 server a v15 bench runs;
benchbar detects the running server and does not install mariadb@11.8.
A second MariaDB (11.8 on another port) is not needed for development.
Phase 2 says the bench has apps or sites but no env. That is the
cleanup tool case below. Run benchbar repair, not the installer.
The runner is reported outdated after an update. An update that
changed the runner’s template makes every runner written before it
outdated (a new version alone does not, since 0.7.0). benchbar repair
rewrites it; the bench keeps running and picks the new runner up on its
next start.
benchbar in Terminal is older than the app. Since 0.7.1
Homebrew’s and the one line installer’s benchbar hand off to the CLI
inside BenchBar.app. A copy from before 0.7.1 cannot, and doctor’s
“Second CLI” check names it with the command that updates it.
benchbar where shows which CLI runs and which one handed off to it.
An app update stopped half way. The app is already at its new
commit, but the migrate or the build did not run. Doctor warns with
app_update_pending, and benchbar status --json lists the record in
pending_operations. Run benchbar app update NAME again: it runs the
steps that did not finish and nothing else. --discard-pending drops
the record without running anything.
The install in the app stopped. The page shows the failed step with
its fix. Retry runs it again, Open Log shows the full output, and
a finished step is skipped on the second run. The same run in Terminal is
benchbar install, or benchbar repair for a bench that exists. Cancel
a password dialog and that step is skipped, with its command to run
yourself.
status says not_adopted. The folder is a bench, but benchbar does
not manage it: it has no service and no other state. benchbar adopt PATH registers it, and shows the plan first.
PDFs do not print. wkhtmltopdf was skipped or is the Homebrew build.
benchbar doctor says which; benchbar repair installs the official
patched Qt package (Intel binary, Rosetta 2 offered on Apple Silicon,
sudo once). If a Homebrew wkhtmltopdf earlier on PATH shadows the
package, doctor says so. brew uninstall wkhtmltopdf then removes only
the Homebrew build; the package in /usr/local/bin stays and takes
over.
Passwords do not decrypt after a restore. Frappe says “Encryption key
is invalid! Please check site_config.json”, an Email Account stops
connecting, or benchbar pull warns that stored passwords do not
decrypt. Frappe encrypts every stored password (email accounts,
integrations, Password fields) with encryption_key from the site’s
site_config.json, and bench restore never copies it: a restored site
without it generates a new key, which cannot read the old rows.
benchbar pull copies the production key for you. After a restore by
hand, or when production had no key, first copy the local
sites/SITE/site_config.json aside (cp site_config.json site_config.json.bak in that folder), then copy encryption_key from
the production site_config.json into the local one (only that key; the
database password and Redis settings there belong to production), then
bench --site SITE clear-cache. When the production key is lost, the
passwords are too: enter them again in the copy.
Something else. benchbar report writes a redacted zip for a bug
report; attach it to an issue at
https://github.com/askysh/benchbar/issues.
Resetting the MariaDB root password
This changes the root password of the one MariaDB server every bench on this Mac shares. The databases stay, and so do the sites’ own database users, which do not use the root password. For a few minutes MariaDB runs without any password checks, reachable only from this Mac.
Before you start:
- Stop every bench, so none loses its database mid request:
benchbar listshows them,benchbar down --bench-dir PATHstops each. - Back up the sites you cannot rebuild:
benchbar site backup SITE. That needs no root password.
Then, in this order. Phase 00 prints the same steps with your paths.
The examples use mariadb@10.11; brew services list shows the MariaDB
formula your Mac runs, so use that name if it differs.
-
Stop the MariaDB service and start it once without password checks:
brew services stop mariadb@10.11"$(brew --prefix)/opt/mariadb@10.11/bin/mariadbd-safe" --skip-grant-tables --skip-networking & -
Set a new root password; put yours in place of
new-password:mariadb -u root -e "FLUSH PRIVILEGES; ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('new-password');" -
Stop the unprotected server and start the service again:
kill %1brew services start mariadb@10.11 -
Save the new password in the Keychain, then bring the benches back with
benchbar up --bench-dir PATH:MARIADB_ROOT_PASSWORD='new-password' benchbar install
The cleanup tool case
A cleanup tool (Mole’s mo purge, or CleanMyMac’s developer junk
cleanup) can delete env/, node_modules/ and apps/*/public/dist. The symptoms:
benchcommands fail withFileNotFoundErrorforenv/bin/python,- socketio fails with
Cannot find module 'socket.io', - the site loads with no styling because
/assets/*/dist/*.bundle.*returns 404, althoughsites/assets/assets.jsonstill exists.
Doctor detects all three separately (it checks the dist files that
assets.json references), and repair rebuilds only what is missing: the
env (the old one moved to env.broken.<timestamp>), the node
requirements, bench build, then the caches. If CleanMyMac is installed,
doctor warns; add the bench folder to its Ignore List. If Mole is
installed, doctor warns until the bench is in ~/.config/mole/whitelist.
What recovers on its own, and what does not
| Situation | What happens |
|---|---|
| A process crashes | launchd restarts the whole bench after 20 seconds |
| It crashes three times in ten minutes | Auto restart pauses and a notification appears. benchlogs, fix, benchup |
| You reboot | The bench comes back only if it was running before; benchdown keeps it down |
| You edit Python code | The web server reloads, the worker does not: benchrestart |
| You edit JS or CSS | Nothing rebuilds in the lean Procfile: benchwatch while you work |
| Scheduled jobs | The scheduler is opt in: benchbar service --with-schedule, then benchbar restart |
bench update or bench setup procfile | They rewrite Procfile. Procfile.lean is separate and untouched |
The bench log is <bench>/logs/bench.log; benchup keeps the tail of the
previous run in logs/bench.previous.log. benchup refuses to start
when a running bench or another program holds its ports, and asks when
only a stopped bench shares them; benchbar ports setup gives each bench
its own ports.
Migrating from frappe-mac 0.2 or older setups
Benches set up by frappe-mac 0.2 run under com.frappe-mac.<bench>.
benchup on such a bench says so and points at benchbar repair, which
moves the old agent aside and installs com.benchbar.<bench>, starting
the bench again if it was running. frappe-mac keeps working as a name
for benchbar.
Per process LaunchAgents (one each for web, worker, socketio and so on)
and hand made agents are listed by doctor with their launchctl state and
last exit code. Repair boots them out and moves the plists to
~/Library/LaunchAgents-disabled/<timestamp>/. Nothing is deleted.
Names from before 0.3.0 move over on the next benchbar repair: the
# >>> frappe-mac >>> block in ~/.zshrc becomes a # >>> benchbar >>>
block in place, frappe-mac-run.sh in the bench becomes benchbar-run.sh
(the old file goes to the backups once the agent no longer uses it), and
the checkout’s .frappe-local/ folder is renamed to .benchbar/ by the
first command that runs. Older # >>> frappe-bench helpers >>> blocks
are reported so you can remove them by hand.
What benchbar writes
<bench>/benchbar-run.shand<bench>/Procfile.lean~/Library/LaunchAgents/com.benchbar.<bench>.plist- the
# >>> benchbar >>>block in~/.zshrc(and the# >>> benchbar-path >>>block from the installer) $(brew --prefix)/etc/my.cnf.d/frappe.cnfandfrappe-mac-local-only.cnf- the
127.0.0.1 <site>line inside# >>> benchbar >>>markers in/etc/hosts ~/.local/bin/benchbarand~/.local/bin/frappe-mac, links to the checkout, or to Homebrew’s benchbar when one is there~/.local/state/benchbar/bin/benchbar, written by BenchBar.app at launch: a link to the CLI inside the app, which Homebrew’s and the installer’sbenchbarhand off to- the Keychain item
benchbar-mariadb <bench>/logs/.benchbar/state.json, written by the runner<bench>/logs/.benchbar/creating-<site>, a marker whilebench new-siteruns, so an interrupted site is not taken for created<bench>/.benchbar.lock, the bench’s own lock folder during a mutating run- the state folder,
~/.local/state/benchbar(.benchbar/in a git checkout): the remembered benches (benches/<folder>-<hash>.env), and the logs and backups of every run - the port keys in
<bench>/sites/common_site_config.jsonand<bench>/config/redis_*.conf, only when a bench moves to another port block (withbench set-config -gandbench setup redis, after asking and with a backup) <bench>/.benchbar/pulls/<site>-<backup>/(mode 0700), the download ofbenchbar pull: kept after a failed run so the next one resumes, removed after a successful one unless--keep-staging
Every generated file carries a benchbar-template header with a version
and a content hash. Do not edit inside the markers of the shell block or
the hosts block: repair regenerates them.
The phase scripts still work on their own: 00-mac-system-deps.sh,
01-install-bench-and-site.sh and 02-background-service.sh keep their
flags (--yes, --profile, --dry-run, --offline, --repair-bench).
00 exits with code 2 when a manual step is pending, most often a
MariaDB root password that neither the environment nor the Keychain
knows. 01 exits with code 2 for that unknown root password and with
code 3 when you cancel at its plan. --repair-bench only
moves aside a folder that never became a bench; a bench with apps or
sites is always kept and sent to benchbar repair.
Wiping a bench
Wiping a bench deletes it for good: every app checkout in apps/ with
its uncommitted and unpushed work, the virtualenv, the sites with their
uploaded files, and their databases. Nothing can bring it back, which is
why benchbar never deletes a whole bench for you. If you only want a
broken bench working again, try benchbar repair first; if you only
want one site gone, benchbar site drop takes a backup first.
Before you start:
- Push every app branch you want to keep:
git statusandgit log @{u}..in each folder underapps/. - Back up each site you may need and copy the backup out of the bench,
since backups live inside it:
benchbar site backup SITE --with-files, then copysites/SITE/private/backups/somewhere else.
Then, in this order. The examples use ~/frappe-bench; use your
bench’s path.
-
Stop the bench and remove its service. This removes only the launchd agent, the runner,
Procfile.leanand the shell helpers, and leaves the bench itself alone:benchbar down --bench-dir ~/frappe-benchbenchbar uninstall-service --bench-dir ~/frappe-benchThe shell helpers are one block in
~/.zshrcshared by every bench, sobenchupand the other helpers go away for your other benches too. When another bench remains,benchbar repair --bench-dir PATHon it writes the block again. -
Drop each site’s database while the bench folder still exists: the database name and user are only written in the site’s
site_config.json. Look them up, then drop both inmariadb -u root -p(benchbar mariadb-password --yesprints the root password):grep -h '"db_name"' ~/frappe-bench/sites/*/site_config.jsonDROP DATABASE `_1a2b3c4d5e6f`;DROP USER '_1a2b3c4d5e6f'@'localhost';Check the name twice: every bench on this Mac shares one MariaDB server, and
SHOW DATABASES;lists the other benches’ sites too. -
Delete the bench folder. This is the step that cannot be undone:
rm -rf ~/frappe-bench -
Make benchbar forget the bench: delete only that bench’s files in
~/.local/state/benchbar/benches/(or the.benchbarfolder of your checkout). They are named after the folder plus a short hash, for examplefrappe-bench-c7a84bb1.envand, when it exists,frappe-bench-c7a84bb1.site-apps. Leave the rest of the state folder alone: it holds the other benches and the logs and backups of every run.
The site’s line in /etc/hosts can stay; it does nothing without the
bench. To remove the Homebrew formulae as well, when no other bench
needs them: brew uninstall mariadb@10.11 redis node@22 python@3.11.
That keeps MariaDB’s data folder, $(brew --prefix)/var/mysql, with
every other database on the Mac.
Windows and WSL
BenchBar for Windows is a beta. The first place to look is the setup check, read only:
benchbar.exe setup check --jsonEach step has a status and an action. The tray’s Check Your PC
shows the same steps with their buttons. setup run changes the PC, so
run its actions one at a time, and ask first when you do this on someone
else’s PC. Steps that are advice (linger, keepalive, the WSL idle settings
and PATH) do not stop you.
- The bench checks.
benchbar.exe doctorruns the Windows checks, then the CLI’s doctor inside the distro. Each warning names its fix. - A stopped distro. WSL stops a distro after its idle time. The tray
shows a Start button for it.
benchbar.exe setup check --probestarts it to check inside. Report a Bug does not start it. - A restart is pending. When the
rebootstep is missing, restart Windows, then runsetup checkagain. The tray’s Restart Now asks first. - Something else. Use Report a Bug in the tray menu, the wizard footer or next to a failed step. It writes a redacted zip and opens the bug form. See Report a bug.
- SmartScreen blocks
benchbar.exe. The program is unsigned until the signing application is approved. Choose More info, then Run anyway, and try the command again.
Things to avoid
- Do not use the unversioned Homebrew
mariadbformula for the v15 profile. Pin tomariadb@10.11. - Do not
brew install wkhtmltopdf. Use the official patched Qt package, whichbenchbar repairinstalls. - Do not switch MariaDB root to
unix_socketonly. Frappe needs password auth. - Do not delete
$(brew --prefix)/var/mysqlwithout a backup. It holds every database on the machine. - Do not put the bench under an iCloud synced folder such as
~/Desktopor~/Documents. - Do not run
bench updateon a bench you cannot rebuild; it rewritesProcfileand can change the toolchain. - If CleanMyMac, Mole or a similar tool is installed, add the bench folder to its ignore list or whitelist before running any cleanup.