Troubleshooting

Fixes for common bakefile errors - bakebook not found, wrong bakebook type, load failures, wrong Python, dry-run, and completion.

Bakebook not found

BakebookError: No 'bakebook' found in /path/to/project/bakefile.py
Searched in: /path/to/project

bake looks for a variable named bakebook (the default). Fixes:

• The variable has a different name? Select it with -b:

bake -b my_bakebook build

• Running from another directory? Change it with -C, or pick another file with -f:

bake -C /path/to/project build
bake -f tasks.py build

• Check the file actually defines and instantiates the bakebook:

from bake import Bakebook

bakebook = Bakebook()

Wrong bakebook type

BakebookError: Bakebook 'bakebook' must be a Bakebook, got Typer

The bakebook variable must be a Bakebook instance (or a subclass like a bakelib Space). A typer.Typer() app or a plain dict does not work. Tasks use Typer syntax, but the bakebook itself is a Bakebook (see Bakebook).

Directory or file name errors

Directory not found: /path/to/project/bakefile.py
File name must not contain path separators: tasks/bakefile.py
File name must end with .py: bakefile

-f takes a file name only, never a path. Change directories with -C instead:

# Bad: path in -f
bake -f tasks/bakefile.py build

# Good: -C for the directory, -f for the name
bake -C tasks -f bakefile.py build

The first error also appears when bakefile.py simply does not exist yet. Create one with bakefile init.

Import errors and dependency sync

When bakefile.py fails to import because a dependency is missing, bake runs uv sync automatically and retries. If loading still fails:

Failed to load bakebook after dependency sync. Try running `uv cache clean` to resolve potential caching issues.

Fixes, in order:

1. Run uv cache clean and retry.
2. For a PEP 723 bakefile, check that every import is declared in the inline # dependencies block.
3. For a pyproject.toml project, run uv sync --all-extras --all-groups.
4. A traceback here usually means a real bug in bakefile.py. Check it compiles:

python -m py_compile bakefile.py

Wrong Python

bake, bakefile env, and bakefile export reinvoke themselves under the bakefile’s Python. If a module is importable in your shell but not from a task, check which interpreter each command uses:

bakefile which
bakefile find-python

See the bakefile CLI for the full breakdown.

Commands print but never run

Dry-run mode (bake -n) prints commands instead of executing them. Remove -n to run for real. To force specific commands to execute even under dry-run, use override_dry_run (see Context).

Completion not working

bake --install-completion

Then restart the shell or open a new terminal.

Log output too noisy or too quiet

Tune levels per logger with BAKE_LOG, bump verbosity with -v, and switch to JSON logs with --no-log-pretty. See Logging.

Secrets print as **********

Masked by design. SecretStr values stay hidden in bakefile env and bakefile export until you pass -s / --secret. See Settings.