--- name: "Diagnostics" --- # Diagnostic codes Every type-checker error and warning carries a stable `AG####` code, and every `agency lint` finding carries a stable `AL####` code. Look one up with `agency explain ` (e.g. `agency explain AG2005`), or suppress a type-checker one on the next line with `// @tc-ignore AG####`. ## Types and aliases | Code | Message | | --- | --- | | [AG1001](types-aliases.md#ag1001) | Type parameter '{param}' (no default) must come before parameters that have defaults in '{alias}'. | | [AG1002](types-aliases.md#ag1002) | Type '{alias}' is not a value-parameterized type but was given {count} value {argumentWord} (referenced in '{context}'). | | [AG1003](types-aliases.md#ag1003) | {alias} expects at most {max} value {argumentWord}, got {count} (referenced in '{context}'). | | [AG1004](types-aliases.md#ag1004) | '{alias}' is a value-parameterized type and requires value arguments — write '{alias}({formals})' (referenced in '{context}'). | | [AG1005](types-aliases.md#ag1005) | {alias} requires at least {min} value {argumentWord} (referenced in '{context}'). | | [AG1006](types-aliases.md#ag1006) | Type alias '{alias}' is not defined (referenced in '{context}'). | | [AG1007](types-aliases.md#ag1007) | Generic type '{alias}' requires type arguments (referenced in '{context}'). | | [AG1008](types-aliases.md#ag1008) | {alias} expects {expected} type {argumentWord}, got {count} (referenced in '{context}'). | | [AG1009](types-aliases.md#ag1009) | Unknown generic type '{alias}' (referenced in '{context}'). | | [AG1010](types-aliases.md#ag1010) | Type '{alias}' is not a generic type (referenced in '{context}'). | | [AG1011](types-aliases.md#ag1011) | {alias} expects at most {max} type {argumentWord}, got {count} (referenced in '{context}'). | | [AG1012](types-aliases.md#ag1012) | {alias} requires at least {min} type {argumentWord} (referenced in '{context}'). | | [AG1013](types-aliases.md#ag1013) | `{name}` is not a type; {hint} | | [AG1014](types-aliases.md#ag1014) | Cannot cast `{from}` to `{to}` because neither type fits the other. If this is intentional, write `{expr} as unknown as {to}`. | | [AG1015](types-aliases.md#ag1015) | A checked cast validates the value at runtime, and `{type}` has no schema to validate against. Remove the `!` to cast without checking. | | [AG1016](types-aliases.md#ag1016) | A cast is not allowed in this position. Add parentheses: `({left} {op} {right}) as {type}` or `{left} {op} ({right} as {type})`. | | [AG1017](types-aliases.md#ag1017) | This checked cast runs validators that can pause the program, and it cannot be resumed safely in this position. Move it to its own line: `const value = {cast}`. | | [AG1018](types-aliases.md#ag1018) | `{expr}` is a `{from}`. A cast does not unwrap it. Unwrap the Result first, with `match` or `catch`, then cast the value if you still need to. | | [AG1019](types-aliases.md#ag1019) | `{cast}` runs validators that can pause the program, and a module-level initializer or a parameter default cannot pause. Do the cast inside a node or a def. | | [AG1020](types-aliases.md#ag1020) | `{cast}` runs validators that can pause the program, and a handler body cannot pause. Do the cast before the `handle` block and use the value here. | | [AG1021](types-aliases.md#ag1021) | `{expr}?` cannot be lowered in this position. Move it to its own line: `const value = {expr}?`. | | [AG1022](types-aliases.md#ag1022) | `{expr}?` returns from a function, and a module-level initializer or a parameter default is not inside one. Use it inside a node or a def. | | [AG1023](types-aliases.md#ag1023) | `{expr}?` cannot be used inside a handler body. Unwrap the Result before the `handle` block, or match on it here. | | [AG1024](types-aliases.md#ag1024) | `{expr}?` would return from a `parallel` arm, and an arm cannot return early. Do the unwrap inside a def the arm calls. | | [AG1025](types-aliases.md#ag1025) | `{expr}?` cannot be a write target. Unwrap into a variable first, then assign to its field. | ## Assignability and checking | Code | Message | | --- | --- | | [AG2001](checking.md#ag2001) | Type '{actual}' is not assignable to type '{expected}' ({context}). | | [AG2002](checking.md#ag2002) | Type '{actual}' is not assignable to type 'boolean' (condition). | | [AG2003](checking.md#ag2003) | Unknown property '{key}' on type '{expected}' ({context}). | | [AG2004](checking.md#ag2004) | Variable '{name}' has no type annotation (strict mode). | | [AG2005](checking.md#ag2005) | Type '{actual}' is not assignable to type '{expected}'. | | [AG2006](checking.md#ag2006) | For-loop iterable must be an array or Record, got '{actual}'. | | [AG2007](checking.md#ag2007) | {kind} '{name}' has validated parameters but its return type is not a Result type. Validated parameters can short-circuit with a failure, so the return type must be 'Result<...>'. | | [AG2008](checking.md#ag2008) | Property '{field}' is not available on every member of '{union}'; narrow the value (e.g. with a guard) before accessing it. | | [AG2009](checking.md#ag2009) | '.{field}' is only available on a {branch} Result; guard with 'if (isSuccess(r))' / 'if (isFailure(r))', use 'r catch …', or 'match (r) { … }'. | | [AG2010](checking.md#ag2010) | Cannot {op} values of different dimensions ({leftDim} and {rightDim}): '{left}' and '{right}'. | | [AG2011](checking.md#ag2011) | Property '{property}' does not exist on type '{type}'. | | [AG2012](checking.md#ag2012) | Not all code paths return a value in '{fn}'. | | [AG2013](checking.md#ag2013) | The first argument to failure() is the message shown to a person or a model, so it must be a string. Got '{actual}'. | | [AG2014](checking.md#ag2014) | The second argument to failure() is its structured data, so it must be an object. Got '{actual}'. | | [AG2015](checking.md#ag2015) | This function declares '{expected}' as its failure data, so failure() needs a second argument. To allow a failure with no data, declare the return type as 'Result<{success}, {expected} \| null>'. | | [AG2016](checking.md#ag2016) | A Result's second type parameter is its failure data, and failure data must be an object. Got '{actual}' ({context}). A failure's message is always a string and is not named in the type. | | [AG2017](checking.md#ag2017) | failure() cannot take a splat. Codegen appends the checkpoint and function name to every failure() call by position, and a splat of unknown width would displace them. Pass the message and data directly. | | [AG2018](checking.md#ag2018) | The body of '{target}' returns '{actual}', but decorator '{name}' takes a block returning '{expected}'. | | [AG2019](checking.md#ag2019) | Decorator '{inner}' returns '{actual}', but decorator '{name}' above it on '{target}' takes a block returning '{expected}'. | | [AG2020](checking.md#ag2020) | '{target}' is declared to return '{declared}', but decorator '{name}' returns '{actual}'. | | [AG2021](checking.md#ag2021) | The body of '{target}' saves a draft of type '{actual}', but decorator '{name}' takes a block returning '{expected}'. | | [AG2022](checking.md#ag2022) | Parameter '{param}' of '{fn}' has alias '{alias}', which is already the name or an alias of parameter '{other}'. | | [AG2023](checking.md#ag2023) | `{expr}?` needs a `Result`, and `{expr}` is a `{type}`. Only a `Result` can be unwrapped with `?`. | | [AG2024](checking.md#ag2024) | `{expr}?` returns a failure from `{name}` when the Result fails, but `{name}` is declared to return `{type}`. Declare it as `Result<{type}>`, or unwrap with `match` or `catch` instead. | ## Interrupts, effects, and handlers | Code | Message | | --- | --- | | [AG3001](effects.md#ag3001) | The '!' validation syntax is not allowed on handler parameters. Validate the data inside the handler body if needed. | | [AG3002](effects.md#ag3002) | Effect '{effect}' is declared more than once in the same file. | | [AG3003](effects.md#ag3003) | Conflicting payload types for effect '{effect}'. All declarations of an effect must agree on its payload. | | [AG3004](effects.md#ag3004) | Named arguments are not allowed on 'raise'/'interrupt'. Pass the data positionally. | | [AG3005](effects.md#ag3005) | Effect '{effect}' expects data {payload}, but none was supplied. | | [AG3006](effects.md#ag3006) | Effect '{effect}' data field '{field}' is missing. | | [AG3007](effects.md#ag3007) | Effect '{effect}' data field '{field}' has the wrong type. | | [AG3008](effects.md#ag3008) | Effect '{effect}' data does not match the declared {payload}. | | [AG3009](effects.md#ag3009) | Function '{fn}' may throw interrupts [{effects}] but is not inside a handler. | | [AG3011](effects.md#ag3011) | `interrupt` is not allowed inside a callback body (callback registered on '{hook}' may raise [{effects}]). Callbacks fire as side effects; their body cannot pause execution to ask the user a question. Move the `interrupt` into the calling node/function instead, or use a runtime guard if you wanted budget enforcement. | | [AG3012](effects.md#ag3012) | 'raises {ref}' is not an effect set. Declare '{ref}' with 'effectSet' (not 'type'), or use an inline set like '<...>'. | | [AG3013](effects.md#ag3013) | {kind} '{name}' raises effect '{effect}', which exceeds its declared 'raises {declared}'. Add '{effect}' to the clause. | | [AG3014](effects.md#ag3014) | {who} may raise any effect (its type has no 'raises' clause), which exceeds the 'raises <{allowed}>' allowed by type '{type}'. Add a 'raises' clause to the value's type. | | [AG3015](effects.md#ag3015) | {who} raises effect '{effect}', which exceeds the 'raises <{allowed}>' allowed by type '{type}'. Add '{effect}' to the clause, or use a target type that allows it. | | [AG3016](effects.md#ag3016) | '{callee}' can interrupt, and a finalize block cannot contain interrupts. A finalize runs while its scope shuts down, so there is nothing to resume. | | [AG3017](effects.md#ag3017) | Cannot use {kind} at the top level of a file. Top-level code runs at initialization, which cannot branch, loop, or wait — move it inside a node or a function. | | [AG3018](effects.md#ag3018) | A handler cannot be registered at the top level of a file. Handlers must be inside a node or a function, where there is execution for them to guard. | | [AG3019](effects.md#ag3019) | @{tag} names '{field}', which effect '{effect}' does not carry. | | [AG3020](effects.md#ag3020) | @{tag} arguments must be bare field names, each named once (effect '{effect}'). | | [AG3021](effects.md#ag3021) | @{tag} appears more than once on effect '{effect}'. | | [AG3022](effects.md#ag3022) | Conflicting @always scopes for effect '{effect}'. All tagged declarations of an effect must agree. | | [AG3023](effects.md#ag3023) | @{tag} is only valid on an effect declaration. | | [AG3024](effects.md#ag3024) | Unknown capability '{name}' on '{callable}'. Did you mean '{suggestion}'? The capabilities are {known}. | | [AG3025](effects.md#ag3025) | @capabilities arguments must be bare capability names (on '{callable}'). | | [AG3026](effects.md#ag3026) | @capabilities appears more than once on '{callable}'. | | [AG3028](effects.md#ag3028) | @capabilities goes on a def or a node.{hint} | | [AG3029](effects.md#ag3029) | {kind} '{name}' needs the {capability} capability, which the {platform} platform does not have. {path} | | [AG3030](effects.md#ag3030) | {kind} '{name}' raises effect '{effect}', which exceeds its declared 'raises {declared}'. It is raised by decorator '{decorator}'. Add '{effect}' to the clause. | ## Names, scope, and reserved words | Code | Message | | --- | --- | | [AG4001](names.md#ag4001) | '{name}' shadows an imported function. | | [AG4002](names.md#ag4002) | '{name}' is a reserved built-in; cannot be redefined. | | [AG4003](names.md#ag4003) | '{name}' is a reserved built-in type; cannot be redefined. | | [AG4004](names.md#ag4004) | Function '{name}' is not defined. | | [AG4005](names.md#ag4005) | Cannot reassign to constant '{name}'. | | [AG4006](names.md#ag4006) | `{keyword}` is a reserved block keyword. Write `{keyword} { ... }` or `{keyword}(args) { ... }` directly — the `as` keyword is not supported on {keyword} blocks (there's nothing to bind). | | [AG4007](names.md#ag4007) | Variable '{name}' is not defined. | | [AG4008](names.md#ag4008) | '{name}' is not defined in '{module}'. | | [AG4009](names.md#ag4009) | Cannot find module '{module}'. | | [AG4010](names.md#ag4010) | '{name}' is defined in '{module}' but is not exported. Add the 'export' keyword to its definition. | | [AG4011](names.md#ag4011) | '{name}' is not accessible under --agency-only. It reaches JavaScript's Function or prototype chain, which pure Agency code may not use. | | [AG4012](names.md#ag4012) | Cannot redeclare parameter '{name}' with '{declKind}'. Reads after the redeclare would still see the parameter. Assign to it instead, or pick a different name. | | [AG4013](names.md#ag4013) | {violation} | ## Match and narrowing | Code | Message | | --- | --- | | [AG5002](match.md#ag5002) | match is not exhaustive: missing {missing}. | | [AG5003](match.md#ag5003) | `{name}` here binds the value; it does not test the type. Did you mean `p: {name}` or `is {name}`? | ## Calls, tools, and LLM usage | Code | Message | | --- | --- | | [AG6001](tools.md#ag6001) | 'regex' cannot appear in an llm() structured-output type ({context}); LLMs can't return regex values through JSON. | | [AG6002](tools.md#ag6002) | Cannot interpolate parameter '{param}' in doc string — parameter values are not known when the tool description is sent to the LLM. Use a global variable instead. | | [AG6003](tools.md#ag6003) | .partial() requires named arguments, e.g. fn.partial(a: 5). | | [AG6004](tools.md#ag6004) | Unknown parameter '{name}' in .partial() call. '{fn}' has parameters: {params}. | | [AG6005](tools.md#ag6005) | Argument type '{actual}' is not assignable to parameter type '{expected}' in .partial() call to '{fn}'. | | [AG6006](tools.md#ag6006) | Named arguments are not supported on built-in method '.{method}()'. | | [AG6007](tools.md#ag6007) | Method '.{method}()' expects {expected} argument(s), got {count}. | | [AG6008](tools.md#ag6008) | Method '.{method}()' expects at least {min} argument(s), got {count}. | | [AG6009](tools.md#ag6009) | Method '.{method}()' expects {min}–{max} argument(s), got {count}. | | [AG6010](tools.md#ag6010) | Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '.{method}()'. | | [AG6011](tools.md#ag6011) | Named arguments can only be used with Agency-defined functions, not '{fn}'. | | [AG6012](tools.md#ag6012) | '{fn}' does not accept the named argument '{name}'. Allowed: {allowed}. | | [AG6013](tools.md#ag6013) | Duplicate named argument '{name}' in call to '{fn}'. | | [AG6014](tools.md#ag6014) | Named argument '{name}' on '{fn}' expects type '{expected}', got '{actual}'. | | [AG6015](tools.md#ag6015) | '{fn}' does not accept a block argument. | | [AG6016](tools.md#ag6016) | Expected {expected} argument(s) for '{fn}', but got {count}. | | [AG6017](tools.md#ag6017) | Expected at least {min} argument(s) for '{fn}', but got {count}. | | [AG6018](tools.md#ag6018) | Expected {min}-{max} argument(s) for '{fn}', but got {count}. | | [AG6019](tools.md#ag6019) | Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'. | | [AG6020](tools.md#ag6020) | Splat argument must be an array, got '{actual}' in call to '{fn}'. | | [AG6021](tools.md#ag6021) | Splat element type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'. | | [AG6022](tools.md#ag6022) | Type '{actual}' is not assignable to pipe slot of type '{expected}'. | | [AG6023](tools.md#ag6023) | Splat argument cannot follow a named argument in call to '{fn}'. | | [AG6024](tools.md#ag6024) | Positional argument cannot follow a named argument in call to '{fn}'. | | [AG6025](tools.md#ag6025) | Unknown named argument '{name}' in call to '{fn}'. {valid} | | [AG6026](tools.md#ag6026) | Named argument '{name}' conflicts with positional argument at position {position} in call to '{fn}'. | | [AG6027](tools.md#ag6027) | Positional argument cannot feed variadic parameter '{param}' when it is also bound by name in call to '{fn}'. | | [AG6028](tools.md#ag6028) | Tool '{tool}' has a required function-typed parameter '{param}' that is unbound. Bind it with .partial({param}: <value>) before passing it as a tool. | | [AG6029](tools.md#ag6029) | Tool '{tool}' has a required function-typed parameter '{param}' that is unbound (its type is {type}). Bind it with .partial({param}: <value>) before passing it as a tool. | | [AG6030](tools.md#ag6030) | Tool '{tool}' will be exposed to the LLM without optional function-typed parameter(s): {params}. The function body must be prepared to run with the declared default for each. | | [AG6031](tools.md#ag6031) | saveDraft() cannot be called at module top level — there is no enclosing function, node, or block scope to save a draft for. | | [AG6032](tools.md#ag6032) | A scope can declare at most one finalize block. Combine the logic into one block. | | [AG6033](tools.md#ag6033) | A finalize block cannot go inside {construct}. Declare it at the top level of the function or block body. A finalize is always active, so nesting it in control flow has no meaning. | | [AG6034](tools.md#ag6034) | saveDraft() has no effect inside a finalize block. The value the finalize returns is already the partial result. Return the value instead. | | [AG6035](tools.md#ag6035) | A finalize block cannot go in a node body. Nothing above a node consumes a partial result yet. Put the finalize in a function or a guard block instead. | | [AG6036](tools.md#ag6036) | This scope has a finalize block, so a return expression cannot bury a call inside a bigger expression. If the call were stopped, the expression would consume its partial result before the finalize could run. Assign the call to a local first, then return the local. | | [AG6037](tools.md#ag6037) | finalize binder '{name}' collides with a variable that already exists in this scope. Pick a fresh name. The finalize body reads the scope's locals directly, so a colliding binder would silently shadow the local. | | [AG6038](tools.md#ag6038) | finalize yields a single value — the scope's saved draft. Use one binder: finalize as {name} { ... }. | | [AG6039](tools.md#ag6039) | Parameter '{name}' on '{fn}' has no default but comes after a defaulted parameter. Put defaulted parameters last, so an omitted argument is always a trailing one. | | [AG6040](tools.md#ag6040) | '{expr}' is passed as a tool, but it is a value of type '{actual}', not a function.{shadowHint} | | [AG6041](tools.md#ag6041) | Decorator '{name}' on '{target}' expects '{param}: {expected}', got '{actual}'. | | [AG6042](tools.md#ag6042) | '{name}' is an alias of parameter '{param}' of '{fn}'. In Agency code, use '{param}'. | | [AG6043](tools.md#ag6043) | '{name}' is declared as a decorator, but {problem} | | [AG6044](tools.md#ag6044) | '{name}' is not a decorator, so '@{name}' cannot go on '{target}'. Declare it as `decorator def {name}(...)`. | | [AG6045](tools.md#ag6045) | '{name}' has a decorator's parameters but is not declared as one: a parameter with a default comes before its last two, which only the call record and the block may follow. Declare it as `decorator def {name}(...)`, or put the defaulted parameter last. | ## Static init, config, and imports | Code | Message | | --- | --- | | [AG7001](static-init.md#ag7001) | Only 'static const' declarations can be exported. Use 'export static const {name} = ...' instead. | | [AG7002](static-init.md#ag7002) | {contextLabel} cannot call `{builtin}(...)` — {reason}, but static initializers run once at process startup before any per-run state exists. Move this call into a node or a function called from a node. | | [AG7003](static-init.md#ag7003) | {contextLabel} cannot `interrupt(...)` — interrupts pause the per-run execution stack, but static initializers run once at process startup before any agent run has begun. Move this into a node body. | | [AG7004](static-init.md#ag7004) | Cannot reassign static `{name}` at module top level — statics are immutable after initialization. Use a global (`const`/`let` without `static`) if you need a mutable value. | | [AG7005](static-init.md#ag7005) | Cannot mutate static `{name}` via `.{method}(...)` at module top level — statics are deep-frozen after initialization. Use a global (`const`/`let` without `static`) if you need a mutable value. | | [AG7006](static-init.md#ag7006) | Function '{name}' cannot be both destructive and idempotent — those markers are contradictory. Pick one. | | [AG7007](static-init.md#ag7007) | Type '{alias}' takes value argument '{name}', which is {what}. A value argument must be a literal, a 'static const', an imported name, or a value parameter of the enclosing type alias. | | [AG7008](static-init.md#ag7008) | {contextLabel} calls `{fn}`, which may interrupt [{effects}]. Interrupts pause the per-run execution stack, but static initializers run once at process startup before any agent run has begun. Move this into a node body, or answer it at the site by ending the statement with `with approve`. | ## Code templates and holes | Code | Message | | --- | --- | | [AG8001](templates.md#ag8001) | This file is a template with unfilled holes ({names}) and cannot be run directly. Load it with `loadTemplate` and fill it first. | | [AG8002](templates.md#ag8002) | The hole `#{name}` is in a position that gives it no expected type. Annotate it, for example `#{name}: string`. | | [AG8003](templates.md#ag8003) | Generator '{name}' may raise {effects}, so it cannot run at compile time. Compilation installs no interrupt handlers, so those operations could not complete anyway. Move the effectful work out of the generator. | | [AG8004](templates.md#ag8004) | Generator '{name}' cannot be checked for effects: {reason}. An empty effect list from an incomplete reading means nothing, so it is refused rather than run. | | [AG8005](templates.md#ag8005) | `{name}` must be imported from another file to be used in a splice. A generator cannot be defined in the file that splices it, because it has to be compiled first. | | [AG8006](templates.md#ag8006) | The generator `{name}` reaches non-Agency code through `{importPath}`. Running a generator loads its file and every file that one imports, and loading a JavaScript module runs it, even when the generator calls nothing from it. JavaScript raises no interrupts and cannot be checked. Move `{name}` into a file that imports only `std::` modules and relative `.agency` files, and check what those files import in turn: one of them importing a JavaScript package is the same problem one step down. If the generator itself needs the JavaScript, set `allowNonAgencyGenerators` in your config, which switches this check off for every generator. | | [AG8007](templates.md#ag8007) | The generator `{name}` returned a `{actual}` fragment, but this splice is in {position} position and needs a `{expected}` fragment. | | [AG8008](templates.md#ag8008) | The generator `{name}` failed while running: {reason} | | [AG8009](templates.md#ag8009) | A generator module cannot itself contain a splice. Move the inner generation into a separate module. | | [AG8010](templates.md#ag8010) | Generated code refers to `{name}`, which it neither declares nor imports. Generated code may use only names it declares itself and names it imports. | | [AG8011](templates.md#ag8011) | The splice argument `{name}` is declared in this file, so it does not exist yet when the generator runs. Splice arguments may be literals, code literals, or imported names. | | [AG8012](templates.md#ag8012) | The generator `{name}` declares `{declared}`, which this file already declares. Generated declarations may not replace existing ones. | | [AG8013](templates.md#ag8013) | The generator `{name}` produced an exported declaration (`{declared}`). Generated declarations cannot be exported yet, because other files resolve imports without running generators. Remove the `export`. | | [AG8014](templates.md#ag8014) | The generator `{name}` returned {kind}, which cannot sit at the top level of a file. Top-level code runs at initialization, which cannot branch, loop, or wait. | | [AG8015](templates.md#ag8015) | `{name}` is not defined in this template. A template can only use names it declares or imports itself, because a hole hides whatever fills it. Move the code that defines `{name}` into this template, or move the code that uses it into the fragment that defines it. | | [AG8016](templates.md#ag8016) | `{file}` contains a splice, and generator execution was declined for this check, so `{name}` was not run. | | [AG8017](templates.md#ag8017) | Generated code from `{generator}` uses the name `{name}`. Names starting with two underscores are reserved for the compiler. | ## Lint | Code | Message | | --- | --- | | [AL0001](lint.md#al0001) | '{name}' is imported but never used. | | [AL0002](lint.md#al0002) | '{name}' is exported but has no docstring. | | [AL0003](lint.md#al0003) | '{name}' is already available without an import. | | [AL0004](lint.md#al0004) | failure({message}) rebuilds '{result}' and drops its flags. Return '{result}' itself. |