Errors¶

fnloom raises as early as it can, and every message names the culprits, so you're never left guessing which name was wrong.

• A mistake in the graph is caught when you build.
• A mistake in a request is caught when it's planned, before any node runs.

The examples use this module and driver:

# file: pricing.py
def total(price: float, quantity: int) -> float:
    """What the line costs."""
    return price * quantity


def label(total: float, currency: str = "EUR") -> str:
    """The price as shown to a customer."""
    return f"{total:.2f} {currency}"

import fnloom
import pricing

driver = fnloom.build(pricing)

When you build¶

When you decorate¶

@parameterize and its shorthands check their rows when the module is imported, listing every culprit in one message (Q82):

When you execute or prepare¶

Each error lists every offending name, sorted. A missing input also names each node that needs it, or says that you requested it as an output. A request is checked in the order below, and the first kind of mistake found is the one raised:

driver.execute(["nope"])
# raises ValueError: unknown outputs: 'nope'
driver.execute(["label"], inputs={"price": 1.0, "quantity": 2, "typo": 3})
# raises ValueError: unknown inputs: 'typo'
driver.execute(["label"], overrides={"tota": 5.0})
# raises ValueError: unknown overrides: 'tota' (did you mean 'total'?)
driver.execute(["label"], inputs={"price": 1.0})
# raises ValueError: missing inputs: 'quantity' (needed by 'total')
driver.execute(["total", "price"])
# raises ValueError: missing inputs: 'price' (requested as an output, needed by 'total'); 'quantity' (needed by 'total')

An unknown name is followed by (did you mean 'x'?), after a space, when a node is close to it: the closest one that difflib.get_close_matches finds at cutoff 0.8, as for 'tota' above. Only validate, which lists every problem at once, suggests a name for a missing input: the closest supplied name that is no node of the graph, so a misspelled key and the input it was meant for point at each other. execute raises that unknown input first, on its own (Q71).

A node that no config variant gave, requested as an output, raises the build's reason: ValueError: no variant of 'foo' matches the config .... A missing input named like a config key gets a second line, since config is never passed to nodes (Q56): 'mode' is a config key; config is not passed to nodes: supply it in inputs=.

The arguments are checked too:

driver.execute("label")
# raises TypeError: final_vars must be a sequence of names, not a single str

inputs and overrides are keyword-only, so a mapping passed positionally is a TypeError instead of being mistaken for one of them.

Some mistakes are found only with a setting, or with a function in final_vars. A function's problem is raised with the request's other output problems, each kind on its own line, in one error:

Type checks on a run¶

Before any node runs, each input the run reads and each override is checked against its node's type. Every value that doesn't fit gets its own line, sorted. The first call below raises with a second line too, quantity: expected int, got float:

driver.execute(["label"], inputs={"price": "cheap", "quantity": 2.5})
# raises ValueError: price: expected float, got str
driver.execute(["label"], overrides={"total": "ten"})
# raises ValueError: total: expected float, got str

None is a mismatch too, unless the type admits it: Optional[T], T | None, object, Any, Literal[None], or a TypeVar that is free or whose bound or a constraint admits it (Q79). Annotate the parameter float | None to accept it. A fixed-length tuple is checked by length and by item, so (1,) for tuple[int, str] is refused (Q80):

driver.execute(["label"], inputs={"price": None, "quantity": 2})
# raises ValueError: price: expected float, got NoneType

A value checked against an annotation that didn't resolve at build, such as a name imported only under TYPE_CHECKING, raises a TypeError instead, listing the plain mismatches with it (Q81): amount: cannot check a value against unresolved 'Decimal': it did not resolve when the graph was built; import what it names at run time, not only under TYPE_CHECKING. An extracted field names its producer and field first.

A custom value check can admit a value these refuse; one that raises fails the run with its own exception, not a ValueError.

Build with Builder.without_input_type_checks() to skip these (see Type checks). With Builder.with_deep_type_checks(), a collection's items are checked too, and with Builder.with_numeric_widening() an int fits float (see Deep checks and numeric widening). A check gives up when more than 10,000 of its questions are open about one value at once, which a value of any size or depth never reaches: only the type's nesting is open about one value. Only a cycle no check can see, such as a type made afresh on each reading, piles questions onto one value, and raises TypeError: value too cyclic to check against ..., the type cut to 200 characters.

When you run a prepared plan¶

A prepared plan accepts the input and override names it was compiled for, and no others:

plan = driver.prepare(["label"], inputs={"price": 0.0, "quantity": 0})
plan.run(inputs={"price": 1.0})
# raises ValueError: inputs ['price'] differ from the prepared ['price', 'quantity']

When a node raises¶

Your function's own exception reaches you unchanged, with a note naming the node (see Running a graph). With with_output_type_checks, a result its annotation refuses fails the node with a TypeError of its own, score: returned int, expected float, noted the same way; a node that raises keeps its own error. Lineage queries raise ValueError: unknown nodes: ... for a name that isn't in the graph.

When a hook raises¶

A hook that raises stops the run once every hook has seen the event. One error is raised as itself. Several are one ExceptionGroup, and a node's own exception is never lost: it comes first, with its in node note, then the hooks' errors in the order they were raised. A group led by a node's error says so, as in node 'boom' failed and hooks raised. See A hook that raises.

with_hooks refuses a hook it can't call when you attach it: a TypeError for an object that is no fnloom.Hook, or for a method that can't take one event or is an async def, and a ValueError for a hook given twice (Checked when attached).

fnloom does not log a failed node. To have each one logged, with its inputs and traceback, attach fnloom.LogFailures.

An AsyncDriver raises a failed node's exception the same way, after cancelling the nodes still running (see Async). On an AsyncDriver, a sync node that returns a coroutine or another awaitable is an error, never a value:

TypeError: node 'f' is a sync function but returned coroutine, an awaitable; make it an async def, so the async driver awaits it