Skip to main content

Troubleshooting

Common issues when integrating beachcomber with shells, editors, and status bars.

Daemon not running​

The daemon is socket-activated — it starts automatically on the first comb call. If comb s exits with a connection error and comb --version works, the binary is likely not on the PATH that your tool (starship, tmux, a bar program) is running under. See comb not found in non-interactive shells below.

For deeper investigation (log location, log level, foreground mode), see the Debugging page.

Verifying a query​

Before adding a comb g call to any tool's config, test it directly in your terminal:

# comb g returns plain text by default. g = get, no suffix needed.
# Path-scoped provider — pass a directory
comb g git.branch .

# Global provider — no path needed
comb g battery.percent

If the command returns nothing, the provider has no data for the current context. This is normal — for example, git.branch returns empty outside a git repository, and kubecontext.context returns empty when no context is set.

Path-scoped providers return empty or wrong data​

Providers like git, terraform, conda, python, direnv, mise, and asdf are path-scoped. They require a directory argument so beachcomber knows which project to query.

In shells, pass . and the shell's working directory is used:

comb g git.branch .

In tmux #() format strings, the command runs in the tmux server's working directory, not the pane's. Use tmux's format variable:

#(comb g git.branch "#{pane_current_path}")

In bar programs (polybar, waybar, sketchybar), . resolves to wherever the bar process started. Always pass an absolute path:

comb g git.branch /home/yourname/myproject

Global providers (battery, load, network, kubecontext, gcloud, aws, hostname, uptime, user) do not take a path argument.

Stale data​

The daemon polls providers on a timer. If you just switched branches or changed a context, the cache may not have refreshed yet. Force an immediate refresh (r is the short form of refresh):

comb r git .

See CLI commands for every command and its short form.

comb not found in non-interactive shells​

Some tools (starship, tmux, bar programs) run commands in non-interactive shells that may not source your .zshrc or .bashrc. If comb is installed to a path only added by your interactive shell config, those tools will not find it.

Check:

/bin/sh -c 'which comb'

If this returns nothing, either:

  • Add the directory containing comb to /etc/paths (macOS) or /etc/environment (Linux)
  • Use the absolute path to comb in your config

Provider not available​

If a key always returns empty, the provider may not be enabled or supported on your platform:

comb l

This shows all registered providers. Check your ~/.config/beachcomber/config.toml if a provider you expect is missing. See the built-in providers reference for every provider and its fields, and platform notes for fields that need optional components (e.g. UPower on Linux for battery.time_remaining).

First query is slow​

On the first query for a provider, the daemon may not have a cached value yet and executes the provider inline. Subsequent queries return the cached value immediately.

To eliminate this delay after a cd, install the chpwd hook — it pokes relevant providers in the background whenever you change directory, so the cache is warm by the time your prompt renders.

Socket discovery​

SDKs and the CLI find the daemon socket in this order:

  1. Config file override (if set in ~/.config/beachcomber/config.toml)
  2. $XDG_RUNTIME_DIR/beachcomber/sock
  3. $TMPDIR/beachcomber-<uid>/sock

Run comb s to see the active socket path. In neovim, check what the environment resolves to: :lua print(vim.env.XDG_RUNTIME_DIR).

Nerd Font glyphs not rendering​

Several integration examples use Nerd Font icons (branch symbol, battery, kubernetes). If these appear as boxes or question marks, your terminal font does not include the glyphs. Install a Nerd Font or replace the icons with text labels in your config.