Errors & notes¶

module 'footman' has no attribute ⟨name⟩

config key 'tasks' expects a filename string (got ⟨filename⟩)

⟨path⟩: a JSON object's keys are text — dict keys must be str, not ⟨getattr(args[0], '__name__', args[0])⟩

⟨path⟩: expected an array, got ⟨_json_name(value)⟩

⟨path⟩: expected an object for ⟨target.__name__⟩, got ⟨_json_name(value)⟩

⟨path⟩: expected an object, got ⟨_json_name(value)⟩

⟨path⟩: expected ⟨_phrase(target)⟩, got ⟨_json_name(value)⟩

⟨path⟩: expected ⟨_phrase(target)⟩, got ⟨_json_name(value)⟩

⟨path⟩: must be one of ⟨'|'.join(choices)⟩ (got ⟨value⟩)

⟨path⟩: the annotations of ⟨target.__name__⟩ did not resolve (⟨exc⟩) — a stdin payload dataclass and everything it names must be module-level, where `eval_str` can see them

⟨path⟩: the document has no ⟨name⟩ field and ⟨target.__name__⟩.⟨name⟩ has no default

enum member ⟨name⟩ projects to ⟨token⟩, outside the contract's token grammar (lowercase ASCII letters, digits, '-') — rename the member

enum members ⟨a.member.name⟩ and ⟨b.member.name⟩ spell ⟨sorted(clash)⟩ ambiguously on the command line — the contract refuses rather than picking

enum members ⟨seen_tokens[token]⟩ and ⟨member.name⟩ both project to token ⟨token⟩ — rename one

Annotated[…, ⟨name⟩]: a bare callable is not a marker — wrap it to say what it means: suggest(⟨name⟩)

expects ⟨type_phrase(tags)⟩ (got ⟨value⟩)

expects ⟨type_phrase(tags)⟩ (got ⟨value⟩)

field ⟨fields[0].name⟩ takes ⟨tags[0]⟩, got ⟨value⟩

⟨value⟩ is not a valid ⟨element.__name__⟩

builtins.discovery_mode = ⟨value⟩ in ⟨_paths.footman_config_file()⟩: one of ⟨', '.join(DISCOVERY_MODES)⟩

builtins.user in ⟨_paths.footman_config_file()⟩: a list of entry-point names (user = ["acme_devkit"]), not ⟨value⟩

⟨source⟩: unknown cascade mode ⟨value⟩ — use 'none' (this directory only), 'repo' (the repository, default), or 'filesystem' (across repositories)

`completion.max_age` expects a duration — seconds, or a number with a unit ("30s", "10m", "1h", "1d"), or "off" (got ⟨value⟩)

`sort` expects true (list tasks alphabetically) or false (definition order, the default) — got ⟨raw⟩

⟨path⟩: a ⟨sniffed[0].upper()⟩ byte-order mark — ⟨_UTF8_ONLY⟩

⟨path⟩: not a regular file — config is read from one

⟨path⟩: not valid UTF-8 (⟨exc.reason⟩ at byte ⟨exc.start⟩) — ⟨_UTF8_ONLY⟩

⟨type(value).__name__⟩ is not JSON-serialisable

result.⟨name⟩ is read-only in post_task — observers see, never judge. Amend verdicts in the review window instead (pre_record, where set_returned also lives), or veto with fail(reason, code).

task.⟨name⟩ is read-only — per-plugin scratch goes on task.state, per-task environment in task.env

task.args is not readable at pre_bind — nothing is bound yet; read the values in pre_task, the post-bind moment

task.state is per-plugin, so it is only reachable inside a lifecycle hook

--⟨cli⟩ is required and nothing supplied it — pass --⟨cli⟩ (a terminal is needed to prompt; --no-input and --json never ask).

--⟨cli⟩ is required and reads stdin — pipe a document in, redirect a file (< payload), or pass --⟨cli⟩

--⟨cli⟩ is required and the JSON document on stdin has no ⟨peeled.stdin.field⟩ field — add the field, or pass --⟨cli⟩

<⟨param.name⟩> is required and reads a JSON document from stdin — pipe one in, or replay a fixture (< payload.json)

rel=… needs a managed base and cwd='unmanaged' has none — use cwd='asinvoked' for a pinned launch-directory base

stdin holds a JSON ⟨type(document).__name__⟩, not an object — a stdin(field) parameter reads one top-level key

stdin is not valid UTF-8 (⟨exc⟩) — bind the parameter as `bytes` to read the raw stream

stdin was empty; expected a JSON document

⟨label⟩ cannot be a ⟨peeled.container.__name__⟩ of ⟨name⟩: ⟨name⟩ is not hashable

⟨label⟩ expects a value, not true/false (got ⟨raw⟩)

⟨label⟩ expects true or false (got ⟨raw⟩)

⟨label⟩ must be one of ⟨'|'.join(choices)⟩⟨extra⟩ (got ⟨value⟩)

⟨label⟩ takes values in groups of ⟨size⟩ (⟨group.label()⟩) — got ⟨len(parts)⟩, which leaves ⟨len(parts) % size⟩ over

⟨label⟩: the ⟨marker.field⟩ field is a JSON ⟨type(value).__name__⟩, not a single value

⟨label⟩: ⟨value⟩ does not satisfy ⟨peeled.path_req⟩

⟨self._reader⟩ cannot read its own value — it is the one being resolved

⟨self._reader⟩ may only read parameters declared before it, and ⟨key⟩ comes after — so it has no value yet. Move ⟨key⟩ above ⟨self._reader⟩ in the signature.

fetch: backend ⟨name⟩ is not installed — `pip install ⟨name⟩`, or leave [fetch] backend unset to use the stdlib

fetch: no usable backend (not even urllib?)

fetch: unknown backend ⟨name⟩ — choose one of ⟨options⟩

fetch: ⟨url⟩ — HTTP ⟨exc.code⟩ ⟨exc.reason⟩

fetch: ⟨url⟩ — HTTP ⟨response.status_code⟩

fetch: ⟨url⟩ — curl: ⟨done.stderr.strip()⟩

fetch: ⟨url⟩ — nothing downloaded and nothing cached

fetch: ⟨url⟩ — sha256 mismatch
  expected ⟨sha256.lower()⟩
  received ⟨actual⟩

fetch: ⟨url⟩ — the body ended early: ⟨received⟩ of ⟨total⟩ bytes

fetch: ⟨url⟩ — ⟨exc.reason⟩. If this machine needs the system curl (a corporate proxy or TLS store), set `backend = "curl"` under [fetch] — in this project, or once for every project in ⟨_paths.footman_config_file()⟩

fetch: ⟨url⟩ — ⟨type(exc).__name__⟩: ⟨exc⟩

⟨label⟩: this call can never return — ⟨' → '.join([*chain, chain[0]])⟩ waits on itself. A task cannot call (directly or through another task) a task that is waiting for it; declare the order with pre= instead.

⟨name⟩ cannot be called from @⟨moment⟩, which ⟨when⟩. Edit the tree instead (inv.tasks — say pre=[⟨name⟩] on the tasks that need it), or move the call to a per-task moment (@pre_task / @post_task), which runs inside the run and gives the call a real task boundary.

⟨name⟩ declares a serial/exclusive lane, so it cannot be called from a task body — its lane is taken at the task boundary, never mid-body. Declare it as pre=[⟨name⟩] instead.

⟨name⟩ is an infinite task, so calling it from a task body would never return. Run it as its own segment, or declare it as pre=[⟨name⟩].

task ⟨ctx.task or '?'⟩ reads stdin in a parallel task — declare the value with ask(), or mark the task interactive=True to own the terminal.

str expected for environment keys and values

lane ⟨name⟩ is already declared at ⟨taken⟩ — one binding per resource. Share it by importing that handle; a second declaration would make two lanes that never contend.

task ⟨ctx.task or '?'⟩ forks — forking a threaded process is unsafe (the child can inherit locks mid-hold). Prefer run()/subprocess, or mark the task serial.

task ⟨ctx.task or '?'⟩ reads the process cwd, which is not this task's directory (⟨ctx.cwd⟩) — a parallel run never chdirs. cwd() is the directory you want.

task ⟨ctx.task or '?'⟩ spawns via raw subprocess — footman filled in ⟨' and '.join(filled)⟩ from the task context. Prefer run() for capture and reporting, or pass cwd=/env= to make it deliberate.

task ⟨ctx.task or '?'⟩ spawns worker processes in-process — they inherit the real environment (run-wide state like colour is published there), but not the task's overlay. A tool that parallelises itself loses little in the serial lane: mark the task serial.

task ⟨ctx.task or key⟩ sets ⟨key⟩ via os.environ — footman scoped it to this task (children see it, siblings don't). Say it on purpose with env= / ctx.env.

task ⟨name or '?'⟩ waiting for ⟨what⟩⟨held⟩

dynamic choices from ⟨name⟩() failed: ⟨type(exc).__name__⟩: ⟨exc⟩ — fix the completer, or pass suggest(fn, strict=False) if this data is best-effort

**⟨param.name⟩ is not supported — declare named parameters, or accept KEY=VALUE pairs with a dict[str, str] parameter

<help>: 'help' is a reserved parameter name — it maps to --help, which footman intercepts anywhere on the line to show help and never run a task, so the option could never be reached. Rename it (e.g. show_help). It is the only reserved name: every other global must come before the first task, so a task parameter may reuse it (fm deploy --json binds --json to deploy).

<⟨param.name⟩>: Arg[…] needs a default — an optional positional's absence must mean something

<⟨param.name⟩>: Arg[…] takes at most one token; a many-valued positional is already optionalable as `Many[…]` with a default

<⟨param.name⟩>: a dict parameter reads stdin whole (a JSON object) — stdin(field)/stdin(lines=True) do not apply

<⟨param.name⟩>: annotation ⟨element⟩ did not resolve — a stdin payload type and everything it names must be module-level, where `eval_str` can see them

<⟨param.name⟩>: annotation ⟨peeled.element⟩ did not resolve — a stdin payload type and everything it names must be module-level, where `eval_str` can see them

<⟨param.name⟩>: default(…) needs a declared default to sit on — a plain Python call of the task, with no run around it, has nothing else to fall back to

<⟨param.name⟩>: env() is not supported on dict parameters

<⟨param.name⟩>: env(⟨peeled.env⟩) needs a default — an env fallback makes the parameter optional, so it needs somewhere to fall

<⟨param.name⟩>: stdin(lines=True) needs a list parameter — each line binds as one element

<⟨param.name⟩>: stdin(⟨marker.field⟩) binds a single value — a list parameter reads lines (stdin(lines=True)) or a JSON array (bare stdin)

<⟨seen_optional⟩>: an Arg[…] optional positional must come last — <⟨spec['name']⟩> follows it, so which token belongs to whom would be a guess. Reorder, or make <⟨spec['name']⟩> an option.

⟨getattr(fn, '__name__', fn)⟩: Stdout[…] and interactive=True cannot both hold — an interactive task owns the real terminal, uncaptured, and a declaring task's stdout belongs to its return value. Drop one.

the cache and ⟨what⟩ directories are both ⟨cache⟩ — they must differ, because the collector deletes from the cache by age and would eventually delete durable ⟨what⟩. Set ⟨env_var('CACHE_DIR')⟩ or ⟨env_var(var)⟩, or place them apart in the App(...).

dependency cycle: ⟨' -> '.join(cycle)⟩ (check the pre/post declarations of these tasks)

group ⟨dep.name⟩ is a prerequisite but has no @group.default

could not update ⟨rc⟩ (⟨exc⟩) — remove this line yourself: ⟨line⟩

could not update ⟨rc⟩ (⟨exc⟩) — remove this line yourself: ⟨line⟩

nu not found on PATH — install nushell first

pwsh (or powershell) not found on PATH — install PowerShell first

nested tasks use dots: '⟨'.'.join(walk_path)⟩', not '⟨spaced⟩'

nested tasks use dots: '⟨'.'.join(walk_path)⟩', not '⟨spaced⟩'

nested tasks use dots: '⟨prev_path⟩.⟨token⟩', not '⟨prev_path⟩ ⟨token⟩'

⟨dotted⟩ is a group, not a task — name one of its tasks (know: ⟨known⟩)

⟨seg.task⟩: --⟨cli⟩ expects KEY=VALUE (got ⟨pair⟩)

⟨seg.task⟩: --⟨cli⟩ is a flag and takes no value

⟨seg.task⟩: <⟨p['name']⟩> must be one of ⟨'|'.join(known)⟩ — ⟨tok⟩ looks like the next task; did you forget <⟨p['name']⟩>?

⟨seg.task⟩: missing required option(s): ⟨', '.join(missing_opts)⟩

⟨seg.task⟩: missing required positional(s): ⟨', '.join(missing)⟩

⟨seg.task⟩: ⟨name⟩ is a global option — it goes before the first task name

⟨token⟩ is an incomplete address (know: ⟨known⟩)

⟨token⟩ is not a task address — addresses are dot-separated names with no empty segments, like 'docs.serve'

⟨token⟩: ⟨dotted⟩ is a task, not a group — nothing lives beneath it

⟨where⟩: ⟨label⟩ expects ⟨expected⟩ (got ⟨value⟩)

⟨where⟩: ⟨label⟩ must be one of ⟨listing⟩⟨extra⟩ (got ⟨value⟩)⟨hint⟩

⟨where⟩: ⟨label⟩ must be ⟨expect⟩ (got ⟨value⟩)

⟨where⟩: ⟨label⟩ must be ⟨phrase⟩ (got ⟨value⟩)

⟨where⟩: ⟨label⟩ takes values in groups of ⟨size⟩ (⟨group['label']⟩) — got ⟨count⟩, which leaves ⟨count % size⟩ over

⟨where⟩: ⟨label⟩ takes ⟨want⟩ — got ⟨count⟩

computed default ⟨name⟩ has no symbolic phrase

post_step hook ⟨name⟩ failed observing ⟨result.shown⟩: ⟨type(exc).__name__⟩: ⟨exc⟩

pre_record hook ⟨name⟩ failed reviewing ⟨shown⟩: ⟨type(exc).__name__⟩: ⟨exc⟩

step .opts() got unknown option(s) ⟨unknown⟩; valid options are ⟨valid⟩. A step is anonymous, so boundary policy (confirm, sharing, gates) needs a declared task to live on.

step ⟨label⟩ yielded ⟨yielded⟩ — a step's yields are checkpoints and carry nothing out. Write a bare `yield`; read the draft with `view = yield`; return the step's value with `return`.

step('title') is the block form — pass the title once, positionally; title= belongs to the decorator/expression forms (step(fn, title=…))

step() lifts a callable or opens a titled block; got ⟨type(target).__name__⟩

step() needs its subject: a function to lift (@step / step(fn, title=…)) or a title string for the block form (with step('…'):)

the console follows interactive task bodies — claim it with @task(interactive=True) (or lanes=(console_lane,) on the task); a step-level console hold waits for a payload that needs one.

step .opts(color=⟨color⟩) expects one of auto|never|always — auto follows the run's own decision

include(⟨dotted⟩): failed to import (⟨type(exc).__name__⟩: ⟨exc⟩)

include(⟨module.__name__⟩): the module registered no tasks and has ⟨detail⟩ to adopt — define tasks with @task/group(), or expose exactly one Group

include(⟨name⟩): the module was already imported outside include(), so its tasks were never captured — call include() before anything else imports it, or have the module expose an explicit Group and pass that instead

include(⟨source⟩): no importable module matches — ⟨segments[0]⟩ is not importable

plugin ⟨name⟩: claimed by more than one distribution (⟨dists⟩)

plugin ⟨name⟩: entry point must resolve to a footman Group (or a module of tasks), got ⟨type(loaded).__name__⟩

plugin ⟨name⟩: failed to import (⟨type(exc).__name__⟩: ⟨exc⟩)

plugin(⟨source⟩): no ⟨ENTRY_POINT_GROUP⟩ entry point matches (installed: ⟨names⟩)

⟨addr⟩ claimed by both ⟨mounted_from(theirs)⟩ and ⟨src.mounted_from⟩ — exclude= one side, retarget with into=, or pass override=True to take the later mount's

⟨verb⟩(): no task or group at ⟨'.'.join(walked)⟩ (⟨parent⟩ has: ⟨known⟩)

⟨verb⟩(): only=/exclude= filter a group's children, and ⟨landing_name⟩ is a task — mount it bare

⟨verb⟩(): ⟨'.'.join(walked)⟩ is a task, not a group — nothing lives beneath it

⟨verb⟩(into=⟨into⟩): ⟨addr⟩ is a task — into= names a group to graft into

⟨verb⟩(⟨source⟩): no task or group at ⟨bad⟩ in the provider's tree (has: ⟨known⟩)

Result.⟨name⟩ is sealed — a committed record is immutable. Amend verdicts in the review window (pre_record), or veto with fail(reason, code) from an observer.

recording(answers=): the sequence for ⟨best⟩ answered its ⟨len(value)⟩ entr⟨plural⟩ and `⟨command⟩` asked for one more — the script is shorter than the story; add an entry, or make it a single value to answer every match

built inside the block but never handed to it: ⟨names⟩. Building an item runs nothing — hand it to the block, p(item), or call it to run it in place. Nothing ran.

given(⟨name⟩) has no answer here — presence is decided when a task's arguments are bound, so call it inside a task body during a run

inherited() works inside a running task — footman resolves the task being shadowed from the one currently running

no terminal is attached, so there is no one to ask. Pass a default for unattended runs, or take the value as a task parameter (a CLI flag) instead.

p(item) queues work for a block, so call it inside the `with` — outside one there is nothing to join.

pre_record hook ⟨hook⟩ failed reviewing ⟨show_label⟩: ⟨type(exc).__name__⟩: ⟨exc⟩

prompt(): ⟨why⟩, so nothing can be asked. Pass a default, or supply the value as a task parameter (a CLI flag).

select(): nothing can be asked (no terminal, or --no-input). Pass default=…, or take the choice as a task parameter.

task ⟨ctx.task or '?'⟩ calls footman.chdir() in a parallel task — the process directory belongs to no one there. The ladder: build paths from footman.cwd() (no chdir at all); or claim lanes=(cwd_lane,) if the real directory only needs to *be* the task's cwd for the duration; or mark the task serial (or exclusive) to own the real globals — footman.chdir() is legal there.

⟨name⟩ does not shadow an inherited task — nothing above it in the cascade defines that name (fm --where ⟨name⟩ lists the chain)

⟨self._task⟩ has not run yet — inside a `with parallel()` block a call is queued, not executed, so it has no value to use there. Read the values from the block's results after it ends.

⟨what⟩ was called inside task ⟨ctx.task or '?'⟩, which is not interactive. Either mark it `@task(interactive=True)` so it owns the terminal, or declare the value as a parameter with `ask()` so footman asks before the task runs.

⟨where⟩ records timing on the *running task*, so it belongs inside a task body, during a run. From a helper thread, make the stream in the body and hand the handle over — the handle remembers its task.

Stream.section(⟨arg⟩=…) takes a datetime or epoch seconds (time.time()), got ⟨type(moment).__name__⟩

a parallel block queues built step items — p(step(fn)(…)) — got ⟨type(item).__name__⟩. Task calls queue themselves; write them as ordinary calls.

chdir(cwd='unmanaged') has no directory to change to

chdir(⟨str(target)⟩) is relative — chdir takes a policy token or an absolute path; a relative suffix goes in rel=…

parallel() runs tasks and steps — ⟨label⟩ is neither. footman only schedules, records, and safely cancels work it owns, and a bare callable is a stranger. Lift it and it earns a receipt too: parallel(step(fn)(…)), or step(fn, title='…') to name a lambda.

recording(answers=): a key is a command prefix — one string ("uv tool list") or a tuple of tokens — not ⟨key⟩

recording(answers=): the answer for ⟨key⟩ is an exception class — pass an instance (⟨value.__name__⟩(...)), which is what the call will raise

recording(answers=): the answer for ⟨key⟩ must be a str (stdout), an int (exit code), a Result, an exception instance, or a list of those — not ⟨type(value).__name__⟩

recording(answers=): the sequence for ⟨key⟩ must be a non-empty list of single answers — one per match

rel=⟨str(rel)⟩ is absolute — rel is a suffix appended to the resolved base; an absolute directory goes first.

run() runs commands; in-process work is a step. Lift the callable — @step on a def, step(fn, title='…') around one you didn't write, or `with step('…'):` over inline code — and it earns a real receipt.

run() takes one command — a string, or a list of tokens — and the ⟨len(args)⟩ after it would be dropped rather than passed to it. Put them in the list: run([⟨spelled⟩])

run(input=…) feeds a subprocess's standard input, and an in-process tool has none — spawn it (in_process=False) to feed it, or pass the value as an argument

Stream.section(): give both start= and end=, or neither — half a window places nothing

Stream.section(⟨name⟩): end is before start — the window is ⟨begin - finish⟩s inside out

fail() means failure and exit code 0 is success — return 0 (or just return) spells stopping early with success

given(⟨name⟩): ⟨ctx.task or 'this task'⟩ has no parameter ⟨name⟩⟨hint⟩ (it has: ⟨listed⟩)

prompt() takes one value — for several, use select(multiple=True) or declare a parameter (Many[…])

prompt(): a secret answer is text — drop type=, or declare the value as a typed parameter with ask(secret=True)

prompt(type=…): ⟨', '.join(named)⟩ decides how a parameter is filled, which a live prompt already settles — declare the value as a task parameter instead (or use select() for a menu)

rel=… needs a managed base and cwd='unmanaged' has none — pass cwd=… explicitly, or use the asinvoked policy

rel=… needs a managed base and cwd='unmanaged' has none — pass cwd=… explicitly, or use the asinvoked policy

rel=⟨str(rel)⟩ is absolute — rel is a suffix on the call's cwd base; pass an absolute directory as cwd=…

run(color=⟨color⟩) expects one of auto|never|always — auto follows the run's own decision

run(shell=…) runs a command *string* through a shell; pass a str, not a list (a list is the shell-free form).

run(timeout=…) needs a process to bound, and this call runs in-process. Spawn it (a list/str command, or .opts(in_process=False) on a tool), or drop the timeout.

run(⟨cmd⟩): ⟨op⟩ is a shell operator, but run() does not use a shell, so it would be passed as a literal argument (the pipeline/redirect would silently not happen). Ask for a shell — run(..., shell=True) or shell='bash' — split into separate run() steps, or pass a list to use ⟨op⟩ as a literal argument.

run(⟨which⟩=True) only applies with a shell — it hardens a shell run. Pass shell=True (or a shell name), or drop ⟨which⟩.

shell='cmd' is Windows-only; use 'bash' or 'pwsh'.

shell=True needs a POSIX shell and none was found. Install one (git bash on Windows), or use shell='pwsh' / shell='cmd'.

shell=⟨kind⟩ is not a known shell. Use True (the policy), a strategy ('posix' / 'native'), or a shell name ('bash', 'zsh', 'sh', 'fish', 'nu', 'pwsh', 'cmd').

shell=⟨strat⟩: ⟨strat⟩ was not found on PATH.

shell=⟨strat⟩: ⟨strat⟩ was not found on PATH.

stream(''): the empty name is the task's own timeline — sections land there via footman.section()

strict=True is not supported for the ⟨kind⟩ shell — it has no errexit/pipefail. Use bash, zsh, sh, or pwsh, or drop strict.

this in-process call needs cwd ⟨cwd⟩ but the process is at ⟨live⟩ — footman no longer chdirs in a parallel task. Run it as a subprocess (which gets cwd= for free), build paths from footman.cwd(), declare @task(cwd='unmanaged'), or pass cwd='unmanaged' on this call if it genuinely doesn't care.

to_argv(): no argv was recorded for `⟨self._shown⟩`. Only a spawned command has separable tokens — an in-process call, a Python callable, or a `run()` given a command *string* never had them apart. Pass a list (`run(['git', 'push'])`) or use a toolroom handle, whose calls always record their argv.

inv.⟨name⟩ cannot be set now: the invocation is editable only at pre_tasks, before anything runs. Per-task state belongs on task.state, and per-task environment on ctx.env.

no task or group named ⟨name⟩ under ⟨where⟩ (know: ⟨', '.join(known) or 'nothing'⟩)

matching() needs a glob, e.g. matching('*.json')

stdin(field) and stdin(lines=True) are exclusive — a field binds one JSON value, lines bind a list of tokens

@task(uses=...) on ⟨key⟩ takes GlobalOption singletons — got ⟨type(used).__name__⟩

@wrap_bind ⟨name⟩ must be a generator function — write `bound = yield` then `result = yield` (a plain trio of functions is @pre_bind + @pre_task + @post_task)

@wrap_task ⟨name⟩ must be a generator function — write `result = yield` where the body runs (a plain pair of functions is @pre_task + @post_task)

@⟨kind⟩ ⟨name⟩ takes ⟨len(positional)⟩ argument(s); ⟨kind⟩ is handed ⟨wanted⟩: def ⟨name⟩(⟨shape⟩)

@⟨task_name(fn)⟩.wrap_bind ⟨name⟩ must be a generator function — two yields: the bind boundary, then the body

@⟨task_name(fn)⟩.wrap_task ⟨name⟩ must be a generator function — write `result = yield` where the body runs

GlobalOption(⟨name⟩): give the bare name — the dashes are the grammar's (and plugin globals are long-form only)

a group cannot be named 'default': the name means "this group's default action" and belongs to a task — declare @⟨self.name⟩.default, or name a task 'default'

expose=⟨value⟩ is not one of ⟨', '.join(EXPOSE_VALUES)⟩

⟨where⟩'s default ⟨task_name(fn)⟩ is interactive but has an empty body, so it fans the group's tasks out in parallel — there is no single body to own the terminal. Give it a real body, or drop interactive.

⟨where⟩: ⟨key⟩ is not a legal name — '.' is the address separator and spaces cannot be addressed; use '_' or '-' inside a name, or nest a group instead

--⟨self.name⟩ has no answer here — a global option is parsed from the command line, so read ⟨type(self).__name__⟩.given inside a task or lifecycle hook, during a run

--⟨self.name⟩ has no value here — a global option is parsed from the command line, so read ⟨type(self).__name__⟩.value inside a task or lifecycle hook, during a run

@wrap_bind ⟨name⟩ finished after one yield — it takes two: `bound = yield`, then `result = yield`

@wrap_bind ⟨name⟩ returned without yielding — it takes two: `bound = yield`, then `result = yield`

@wrap_bind ⟨name⟩ yielded again after the result — two yields exactly

@wrap_task ⟨name⟩ returned without yielding — exactly one `result = yield` marks where the body runs

@wrap_task ⟨name⟩ yielded a second time — one yield exactly; @wrap_bind is the two-yield wrapper that enters at the bind boundary

@⟨task_name(fn)⟩.wrap_bind ⟨name⟩ finished after one yield — two yields exactly (bind, then body)

@⟨task_name(fn)⟩.wrap_bind ⟨name⟩ returned without yielding — two yields exactly

@⟨task_name(fn)⟩.wrap_bind ⟨name⟩ yielded a third time — two yields exactly

@⟨task_name(fn)⟩.wrap_task ⟨name⟩ returned without yielding — exactly one `result = yield` marks where the body runs

@⟨task_name(fn)⟩.wrap_task ⟨name⟩ yielded a second time — one yield exactly

.opts() got unknown option(s) ⟨unknown⟩; valid options are ⟨valid⟩. A task's own parameters go in the call — `t.opts(atomic=True)(x=1)` — not in .opts().

.opts(⟨name⟩=…) needs a hashable value — options key the run's deduplication — but got an unhashable ⟨type(value).__name__⟩

cwd=⟨str(value)⟩ is relative — cwd takes a policy token (⟨', '.join(CWD_TOKENS)⟩) or an absolute path; a relative suffix goes in rel=…

group ⟨self.name⟩ is not runnable: it has no @⟨self.name⟩.default, so there is no action to call. Add a default action, or call a task inside the group directly.

lanes= takes Lane handles, not ⟨type(entry).__name__⟩ (⟨entry⟩). Declare the resource once — db = footman.lane('db', reason='…') — and pass the handle: lanes=(db,). Handles are what make a typo an undefined name instead of a second, silently distinct lane.

rel=… needs a managed base and cwd='unmanaged' has none — use cwd='asinvoked' for a pinned launch-directory base

rel=… needs a managed base and cwd='unmanaged' has none — use cwd='asinvoked' for a pinned launch-directory base

rel=⟨str(value)⟩ is absolute — rel is a suffix appended to the resolved cwd base; an absolute directory goes in cwd=…

retries=⟨retries⟩ — a whole number of EXTRA attempts after the first (retries=2 means up to three runs); omit it for none

timeout=⟨timeout⟩ — a deadline must be a positive number of seconds; omit it for no deadline