> ## Documentation Index
> Fetch the complete documentation index at: https://bakefile.wisl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bake -b my_bakebook build
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bake -C /path/to/project build
bake -f tasks.py build
```

* Check the file actually defines and instantiates the bakebook:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/concepts/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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/concepts/pep723) 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bakefile which
bakefile find-python
```

See the [bakefile CLI](/cli/bakefile) 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](/concepts/context)).

## Completion not working

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/usage/logging).

## Secrets print as \*\*\*\*\*\*\*\*\*\*

Masked by design. `SecretStr` values stay hidden in `bakefile env` and `bakefile export` until you pass `-s` / `--secret`. See [Settings](/usage/settings).