# Troubleshooting
## `no preferred jan directory configured`
```bash
jan use /path/to/jan-cli/examples --root demo.spec.yaml
jan --help
```
`jan use --show` prints the config path and saved directory.
## `no jan entry YAML in …`
The directory needs `scripts.spec.yaml`, `jan.spec.yaml`, or `jan.yaml` — or pass `--root custom.yaml`.
## `missing required utilities on PATH: fzf`
Install the named tool or remove it from the node's `requires:` list. `jan validate --requires` reports these without running leaves.
## `unknown script dependency 'foo'`
The `dependencies:` entry must match another command name in the same tree that has a `path:`.
## `unexpected trailing arguments`
The leaf does not set `exec.passthrough: true`. Add it, or drop the extra args. Typed inputs consume `--name` flags first.
## `place --help immediately after the subcommand prefix`
Put `--help` right after the prefix you want help for, not after passthrough argv. Forward a child's help with `--`:
```bash
jan git r -- --help
```
## Spec include errors
`include:` paths are resolved from the root directory selected by `jan use`. Absolute paths, `..` components, and symlinks that escape that root are rejected both during normal loading and by `jan bundle`.
## `sha256 must be a 64-character hex string`
Remote `jan use`, remote includes, and `exec.url` require a full SHA-256 hex digest.
## `refusing non-HTTPS URL`
Pass `--allow-http` or set `JAN_ALLOW_HTTP=1` only for testing. Prefer HTTPS.
## Package pin errors
uv inline entries need `==` / `===`. pnpm needs `name@major.minor.patch`. gradle needs `group:artifact:version` with an exact version. `project:` forms need the matching lockfile (`uv.lock`, `pnpm-lock.yaml`, `gradle.lockfile`).
## `audit database not found`
No leaf has been logged yet, or `--db` / `JAN_DB` points elsewhere. Run a command without `--no-log`, or pass the correct `--db`.
## Tests print `no tests defined under …`
The path has no `tests:` maps. Declare Given/When/Then cases on the node (names must be `given_…_when_…_then_…`).