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 <code> (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	Type parameter '{param}' (no default) must come before parameters that have defaults in '{alias}'.
AG1002	Type '{alias}' is not a value-parameterized type but was given {count} value {argumentWord} (referenced in '{context}').
AG1003	{alias} expects at most {max} value {argumentWord}, got {count} (referenced in '{context}').
AG1004	'{alias}' is a value-parameterized type and requires value arguments — write '{alias}({formals})' (referenced in '{context}').
AG1005	{alias} requires at least {min} value {argumentWord} (referenced in '{context}').
AG1006	Type alias '{alias}' is not defined (referenced in '{context}').
AG1007	Generic type '{alias}' requires type arguments (referenced in '{context}').
AG1008	{alias} expects {expected} type {argumentWord}, got {count} (referenced in '{context}').
AG1009	Unknown generic type '{alias}' (referenced in '{context}').
AG1010	Type '{alias}' is not a generic type (referenced in '{context}').
AG1011	{alias} expects at most {max} type {argumentWord}, got {count} (referenced in '{context}').
AG1012	{alias} requires at least {min} type {argumentWord} (referenced in '{context}').
AG1013	{name} is not a type; {hint}
AG1014	Cannot cast {from} to {to} because neither type fits the other. If this is intentional, write {expr} as unknown as {to}.
AG1015	A checked cast validates the value at runtime, and {type} has no schema to validate against. Remove the ! to cast without checking.
AG1016	A cast is not allowed in this position. Add parentheses: ({left} {op} {right}) as {type} or {left} {op} ({right} as {type}).
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	{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	{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	{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.

Assignability and checking

Code	Message
AG2001	Type '{actual}' is not assignable to type '{expected}' ({context}).
AG2002	Type '{actual}' is not assignable to type 'boolean' (condition).
AG2003	Unknown property '{key}' on type '{expected}' ({context}).
AG2004	Variable '{name}' has no type annotation (strict mode).
AG2005	Type '{actual}' is not assignable to type '{expected}'.
AG2006	For-loop iterable must be an array or Record, got '{actual}'.
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	Property '{field}' is not available on every member of '{union}'; narrow the value (e.g. with a guard) before accessing it.
AG2009	'.{field}' is only available on a {branch} Result; guard with 'if (isSuccess(r))' / 'if (isFailure(r))', use 'r catch …', or 'match (r) { … }'.
AG2010	Cannot {op} values of different dimensions ({leftDim} and {rightDim}): '{left}' and '{right}'.
AG2011	Property '{property}' does not exist on type '{type}'.
AG2012	Not all code paths return a value in '{fn}'.
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	The second argument to failure() is its structured data, so it must be an object. Got '{actual}'.
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	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	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.

Interrupts, effects, and handlers

Code	Message
AG3001	The '!' validation syntax is not allowed on handler parameters. Validate the data inside the handler body if needed.
AG3002	Effect '{effect}' is declared more than once in the same file.
AG3003	Conflicting payload types for effect '{effect}'. All declarations of an effect must agree on its payload.
AG3004	Named arguments are not allowed on 'raise'/'interrupt'. Pass the data positionally.
AG3005	Effect '{effect}' expects data {payload}, but none was supplied.
AG3006	Effect '{effect}' data field '{field}' is missing.
AG3007	Effect '{effect}' data field '{field}' has the wrong type.
AG3008	Effect '{effect}' data does not match the declared {payload}.
AG3009	Function '{fn}' may throw interrupts [{effects}] but is not inside a handler.
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	'raises {ref}' is not an effect set. Declare '{ref}' with 'effectSet' (not 'type'), or use an inline set like '<...>'.
AG3013	{kind} '{name}' raises effect '{effect}', which exceeds its declared 'raises {declared}'. Add '{effect}' to the clause.
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	{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	'{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	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	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	@{tag} names '{field}', which effect '{effect}' does not carry.
AG3020	@{tag} arguments must be bare field names, each named once (effect '{effect}').
AG3021	@{tag} appears more than once on effect '{effect}'.
AG3022	Conflicting @always scopes for effect '{effect}'. All tagged declarations of an effect must agree.
AG3023	@{tag} is only valid on an effect declaration.

Names, scope, and reserved words

Code	Message
AG4001	'{name}' shadows an imported function.
AG4002	'{name}' is a reserved built-in; cannot be redefined.
AG4003	'{name}' is a reserved built-in type; cannot be redefined.
AG4004	Function '{name}' is not defined.
AG4005	Cannot reassign to constant '{name}'.
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	Variable '{name}' is not defined.
AG4008	'{name}' is not defined in '{module}'.
AG4009	Cannot find module '{module}'.
AG4010	'{name}' is defined in '{module}' but is not exported. Add the 'export' keyword to its definition.
AG4011	'{name}' is not accessible under --agency-only. It reaches JavaScript's Function or prototype chain, which pure Agency code may not use.
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	{violation}

Match and narrowing

Code	Message
AG5002	match is not exhaustive: missing {missing}.
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	'regex' cannot appear in an llm() structured-output type ({context}); LLMs can't return regex values through JSON.
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	.partial() requires named arguments, e.g. fn.partial(a: 5).
AG6004	Unknown parameter '{name}' in .partial() call. '{fn}' has parameters: {params}.
AG6005	Argument type '{actual}' is not assignable to parameter type '{expected}' in .partial() call to '{fn}'.
AG6006	Named arguments are not supported on built-in method '.{method}()'.
AG6007	Method '.{method}()' expects {expected} argument(s), got {count}.
AG6008	Method '.{method}()' expects at least {min} argument(s), got {count}.
AG6009	Method '.{method}()' expects {min}–{max} argument(s), got {count}.
AG6010	Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '.{method}()'.
AG6011	Named arguments can only be used with Agency-defined functions, not '{fn}'.
AG6012	'{fn}' does not accept the named argument '{name}'. Allowed: {allowed}.
AG6013	Duplicate named argument '{name}' in call to '{fn}'.
AG6014	Named argument '{name}' on '{fn}' expects type '{expected}', got '{actual}'.
AG6015	'{fn}' does not accept a block argument.
AG6016	Expected {expected} argument(s) for '{fn}', but got {count}.
AG6017	Expected at least {min} argument(s) for '{fn}', but got {count}.
AG6018	Expected {min}-{max} argument(s) for '{fn}', but got {count}.
AG6019	Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'.
AG6020	Splat argument must be an array, got '{actual}' in call to '{fn}'.
AG6021	Splat element type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'.
AG6022	Type '{actual}' is not assignable to pipe slot of type '{expected}'.
AG6023	Splat argument cannot follow a named argument in call to '{fn}'.
AG6024	Positional argument cannot follow a named argument in call to '{fn}'.
AG6025	Unknown named argument '{name}' in call to '{fn}'.
AG6026	Named argument '{name}' conflicts with positional argument at position {position} in call to '{fn}'.
AG6027	Positional argument cannot feed variadic parameter '{param}' when it is also bound by name in call to '{fn}'.
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	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	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	saveDraft() cannot be called at module top level — there is no enclosing function, node, or block scope to save a draft for.
AG6032	A scope can declare at most one finalize block. Combine the logic into one block.
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	saveDraft() has no effect inside a finalize block. The value the finalize returns is already the partial result. Return the value instead.
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	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	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	finalize yields a single value — the scope's saved draft. Use one binder: finalize as {name} { ... }.
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	'{expr}' is passed as a tool, but it is a value of type '{actual}', not a function.{shadowHint}

Static init, config, and imports

Code	Message
AG7001	Only 'static const' declarations can be exported. Use 'export static const {name} = ...' instead.
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	{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	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	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	Function '{name}' cannot be both destructive and idempotent — those markers are contradictory. Pick one.
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	{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	This file is a template with unfilled holes ({names}) and cannot be run directly. Load it with loadTemplate and fill it first.
AG8002	The hole #{name} is in a position that gives it no expected type. Annotate it, for example #{name}: string.
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	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	{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	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	The generator {name} returned a {actual} fragment, but this splice is in {position} position and needs a {expected} fragment.
AG8008	The generator {name} failed while running: {reason}
AG8009	A generator module cannot itself contain a splice. Move the inner generation into a separate module.
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	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	The generator {name} declares {declared}, which this file already declares. Generated declarations may not replace existing ones.
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	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	{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	{file} contains a splice, and generator execution was declined for this check, so {name} was not run.
AG8017	Generated code from {generator} uses the name {name}. Names starting with two underscores are reserved for the compiler.

Lint

Code	Message
AL0001	'{name}' is imported but never used.
AL0002	'{name}' is exported but has no docstring.
AL0003	'{name}' is already available without an import.