FAQ and Troubleshooting

FAQ and Troubleshooting

General problems when using Beez. For cache-specific issues see Caching Troubleshooting.

build script not found

Beez looks for build.lua in the current working directory. The CLI prints:

Error: build script not found: <path>/build.lua

cd /path/to/your/project
beez build

Commands that do not need build.lua: -h, -v, --config-options, --complete-config-options, --dump-completion, --install-completion.

Commands that do need it: targets, -p, -s, --list, --show-config, --clean-cache, --update, --install.

ReqPack / rqp not found

If build.lua contains reqpack { ... } and Beez cannot find the rqp executable:

ReqPack (rqp) is required to install dependencies. Install it with:
  curl -fsSL https://raw.githubusercontent.com/Coditary/ReqPack/main/install.sh | sh

Install ReqPack, ensure rqp is on PATH, then rerun. Use beez --install to install all declared packages without running a target. See ReqPack Declaration.

reqpack install failed

Beez prints per-package errors when rqp returns structured JSON output, for example:

reqpack install failed:
  npm:vitest: plugin action failed

Fix the failing package or plugin configuration, then run beez --install again.

failed to load build script / failed to load build.lua

The file exists but Lua failed to parse or execute it. At load time the CLI prints:

Error: failed to load build script: <path>/build.lua

During a run, the orchestrator may report failed to load build.lua for the same class of problem.

1. Check syntax errors (missing comma, unclosed brace)
2. Read the Lua error: or DSL error: line printed before the generic message
3. Confirm require("config") paths exist when using beez.config(require("config"))
4. Ensure only supported Lua libraries are used in the DSL sandbox (base and package)

name not found in registry

The CLI target, step, task, or workflow name does not exist.

beez --list tasks
beez --list workflows
beez --list steps

Common causes:

• Typo in beez my-target
• Step exists but no task/workflow exposes it (use beez -s stepname or add a workflow)
• Phase filter -p matches no registered steps

invalid phase request

Rare orchestrator error when the phase name is empty internally. It is not the usual message for a bad -p argument.

Situation	Result
Malformed -p syntax (e.g. generate:, generate:code,)	Parse error, help printed, exit 1
Valid phase with no registered steps	Success, exit 0, nothing executed
Valid phase but wrong scope	Success for that scope if empty; no steps run

For phase and scope issues:

• Use beez --list phases to see registered phases
• Check scope spelling: compile:code not compile/code
• Comma-separated scopes run sequentially; bracket syntax selects explicit scope lists

See Filtering by Phase and Selecting with Phases and Scopes.

step ordering failed

order() declared a dependency cycle, or two steps with overlapping mutate patterns could not be ordered.

1. List steps in that phase+scope: beez --list steps
2. Review order() declarations for cycles
3. Ensure ordered step names match registered name fields exactly

See Order Declaration and Parallel Execution and Dependencies.

task execution failed

A shell command returned non-zero or a Lua callback returned a non-zero exit code.

1. Re-run the failing step: beez -s stepname --verbose
2. Check worker logs in .cache/logs/workers/ (when ui.logging.workers allows)
3. Inspect the run log at ui.logging.run_log_file

Step runs when I expected a cache hit

See Caching Troubleshooting. Quick checks:

• Step has input, output, or mutate patterns
• Output files still exist on disk
• --no-cache not set; cache.enabled is true
• Changed files are covered by input/mutate globs
• Toolchain env vars are in env.hash_vars

Step skipped when it should run

beez --clean-cache build

Then verify artifact patterns and env fingerprint settings. See Cache Keys and Invalidation.

No output / only exit code

--silent or ui.output_mode = "silent" suppresses almost all terminal output. Use echo $? to read the exit code, or run with --verbose.

--show-config fails

Requires a valid build.lua in the current directory so project config can load.

Config key ignored

Check merge order: global → project → env → CLI. Inspect effective values:

beez --show-config

CLI flags override file config for the same run. See Configuration Overview.

unknown ui theme

ui.theme must name an entry in ui.themes. Fix the name or define the palette table. Beez validates the theme when UI settings are resolved (at run time or with --show-config), not when parsing beez.config().

Parallelism seems low

• performance.max_threads caps workers (-j on CLI)
• Steps in the same phase+scope without order() can run in parallel; ordered steps wait on predecessors
• A workflow runs its steps sequentially; only parallel groups overlap

See Parallel Execution and Dependencies and Performance Settings.

Shell completion not working

beez --install-completion
# restart shell or source rc file

Or manually: beez --dump-completion zsh. See Meta and Utility Commands.

Arguments after -- have no effect

Beez parses userOptions after -- but does not pass them to steps yet. Pass values via environment variables or step config instead.

Where are logs?

Log	Default path
Run log	.cache/logs/latest.log
Worker logs	.cache/logs/workers/

Configure under ui.logging. See Logging and Log Files.

Getting more help

Goal	Command / page
List entities	beez --list steps
Inspect config	beez --show-config
Schema keys	beez --config-options
Dry run graph	beez build --dry-run
Verbose subprocess output	beez build --verbose

Related pages

• Caching Troubleshooting - cache hits and misses
• Quick Reference - common commands
• Appendix - appendix index