Troubleshooting

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:

Run uv cache clean and retry.
For a PEP 723 bakefile, check that every import is declared in the inline # dependencies block.
For a pyproject.toml project, run uv sync --all-extras --all-groups.
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.

Getting Started

Concepts

Usage

CLI Reference

bakelib

Examples

Troubleshooting

Bakebook not found

Wrong bakebook type

Directory or file name errors

Import errors and dependency sync

Wrong Python

Commands print but never run

Completion not working

Log output too noisy or too quiet

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

​Bakebook not found

​Wrong bakebook type

​Directory or file name errors

​Import errors and dependency sync

​Wrong Python

​Commands print but never run

​Completion not working

​Log output too noisy or too quiet

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

Bakebook not found

Wrong bakebook type

Directory or file name errors

Import errors and dependency sync

Wrong Python

Commands print but never run

Completion not working

Log output too noisy or too quiet

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