Skip to content

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 list shows them, benchbar down --bench-dir PATH stops 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.

  1. 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 &
  2. 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');"
  3. Stop the unprotected server and start the service again:

    kill %1
    brew services start mariadb@10.11
  4. 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:

  • bench commands fail with FileNotFoundError for env/bin/python,
  • socketio fails with Cannot find module 'socket.io',
  • the site loads with no styling because /assets/*/dist/*.bundle.* returns 404, although sites/assets/assets.json still 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

SituationWhat happens
A process crasheslaunchd restarts the whole bench after 20 seconds
It crashes three times in ten minutesAuto restart pauses and a notification appears. benchlogs, fix, benchup
You rebootThe bench comes back only if it was running before; benchdown keeps it down
You edit Python codeThe web server reloads, the worker does not: benchrestart
You edit JS or CSSNothing rebuilds in the lean Procfile: benchwatch while you work
Scheduled jobsThe scheduler is opt in: benchbar service --with-schedule, then benchbar restart
bench update or bench setup procfileThey 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.sh and <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.cnf and frappe-mac-local-only.cnf
  • the 127.0.0.1 <site> line inside # >>> benchbar >>> markers in /etc/hosts
  • ~/.local/bin/benchbar and ~/.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’s benchbar hand off to
  • the Keychain item benchbar-mariadb
  • <bench>/logs/.benchbar/state.json, written by the runner
  • <bench>/logs/.benchbar/creating-<site>, a marker while bench new-site runs, 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.json and <bench>/config/redis_*.conf, only when a bench moves to another port block (with bench set-config -g and bench setup redis, after asking and with a backup)
  • <bench>/.benchbar/pulls/<site>-<backup>/ (mode 0700), the download of benchbar 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 status and git log @{u}.. in each folder under apps/.
  • 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 copy sites/SITE/private/backups/ somewhere else.

Then, in this order. The examples use ~/frappe-bench; use your bench’s path.

  1. Stop the bench and remove its service. This removes only the launchd agent, the runner, Procfile.lean and the shell helpers, and leaves the bench itself alone:

    benchbar down --bench-dir ~/frappe-bench
    benchbar uninstall-service --bench-dir ~/frappe-bench

    The shell helpers are one block in ~/.zshrc shared by every bench, so benchup and the other helpers go away for your other benches too. When another bench remains, benchbar repair --bench-dir PATH on it writes the block again.

  2. 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 in mariadb -u root -p (benchbar mariadb-password --yes prints the root password):

    grep -h '"db_name"' ~/frappe-bench/sites/*/site_config.json
    DROP 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.

  3. Delete the bench folder. This is the step that cannot be undone:

    rm -rf ~/frappe-bench
  4. Make benchbar forget the bench: delete only that bench’s files in ~/.local/state/benchbar/benches/ (or the .benchbar folder of your checkout). They are named after the folder plus a short hash, for example frappe-bench-c7a84bb1.env and, 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 --json

Each 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 doctor runs 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 --probe starts it to check inside. Report a Bug does not start it.
  • A restart is pending. When the reboot step is missing, restart Windows, then run setup check again. 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 mariadb formula for the v15 profile. Pin to mariadb@10.11.
  • Do not brew install wkhtmltopdf. Use the official patched Qt package, which benchbar repair installs.
  • Do not switch MariaDB root to unix_socket only. Frappe needs password auth.
  • Do not delete $(brew --prefix)/var/mysql without a backup. It holds every database on the machine.
  • Do not put the bench under an iCloud synced folder such as ~/Desktop or ~/Documents.
  • Do not run bench update on a bench you cannot rebuild; it rewrites Procfile and 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.