Diagnostics Reference

Typed data and entry admission

Code	Cause	Action
ProjectEntrypointsInvalid	Invalid or duplicate entry list, or a direct agent entry	Declare entry and entrypoints; call the agent through its authorized strategy
ProjectEntrypointNotAllowed	Workflow absent from the project's entries	Check the selection; declare the authorized workflow and run prepare again
InvalidFieldConstraint	Constraint incompatible with its type, or inconsistent bounds	Use format "digits" on Text, length on text/lists, and min/max on numbers
InvalidFieldDefault	Default violates its type or constraints	Supply a valid static value; see typed data
DateValueInvalid	Invalid date conversion	Supply a real civil date in YYYY-MM-DD format
RecordValueInvalid	Construction or copy violates a field contract	Correct the value before construction; external inputs and outputs are checked too
HumanApprovalExclusionEvidenceRequired	Missing excluded signers or incorrect rule	Have the host attest the source-declared exclude_signers rule

Provider errors expose bounded details: http_status, finish_reason and, when available, incomplete_reason. A handler error retains its cause; receipt_error_code identifies a missing or invalid effect receipt. Without evidence of application, the effect's outcome remains unknown.

Project, agent and handler integration

Code	Cause	Action
StrategyInterfaceRequired	A source strategy call has no explicit output signature	Declare gives and pass every takes argument
StrategyInputTypeMismatch	Strategy argument values do not match the interface	Fix the arguments or source type; recompile
InvocationDepthLimitExceeded	More than 64 nested calls	Bound recursion or flatten the workflow without widening authority
InvalidHumanApprovalCheckpoint / HumanApprovalCheckpointIncompatible	Missing, malformed or AIR-incompatible continuation	Preserve the saved state; use matching AIR and complete current-format checkpoints, without replaying effects
UnknownToolCapability	Unknown capability name	Use the closed list in the tool guide; split operations into distinct tools
MissingTriggerArgument	Required target input not bound	Add with <name> as payload.<field> for a request, or a value for a schedule
AgentDecisionRequired	No deterministic decision or provider configured	Configure --agent-decision-provider on run or serve, or explicit decisions
ToolHandlerReportedError / UnhandledHandlerError	Handler exception	Reproduce run({ request, context }) in a local business test; do not expose secret-bearing messages
TriggerPayloadInvalid	Missing field or invalid type	Fix payload and mapping; a source literal is not fallback for a missing mapped field
TriggerEventPayloadConflict	Same identifier with different content	Do not reuse an identifier for a new event
TriggerReplayRejected	Event already consumed	Recover its result instead of redispatching the effect
ToubaServeDecisionIdentityUnauthorized	Inactive user, unpaired device or missing decision authority	Configure identity and assignment, without disabling checks
ToubaServeSandboxCheckpointStoreInvalid	Inconsistent or corrupt durable state	Preserve files and inspect correlations; do not delete waits to restart
ToubaServeSandboxInvalid	Wrong request or route discriminant	Use /triggers/fire for a trigger and /runs/sandbox for an entrypoint
ToubaServeProjectAirStale	Newer sources or absent AIR	Run prepare --profile dev --mode write, then refresh
ToubaServePreparedProjectInvalid	Invalid, stale or unconfined development preparation	Fix inputs and regenerate preparation
ToubaServeHumanWaitConflict	Decision or resume already claimed	Read that request's state, rather than creating a replacement approval
HandlerEntryUnknownTool	Binding absent from all locked AIRs	Supply every project AIR with repeated --air, or remove a truly obsolete binding
PreparedAirDrift	Derived AIR differs from expected compilation	Regenerate with prepare --mode write; do not edit derived output
HostDecisionJsonInvalid / HostDecisionInvalid / HostDecisionFieldUnknown	Malformed decisions or unknown fields	Use documented selections only; CLI JSON is limited to 64 KiB, with no secret values
HostDecisionTargetUnknown / HostDecisionSelectionInvalid	Undeclared target, grant, handle or access, or duplicate selection	Review source requirements and explicitly select legitimate authority
HostDecisionEffectInvalid / HostDecisionLimitInvalid	Invalid effect contract or limit	Declare the exact contract and strictly positive integer limits
HostDecisionDrift	Requested decisions have not been applied	Review with plan, apply with write, then verify with check
HostDecisionFragmentConflict / BindingFragmentManifestDrift	Competing decisions or fragment drift	Explicitly reconcile fragment and manifest; no automatic authority expansion
HandlerDiagnosticsForbidden	Private diagnostics outside local development	Use a POSIX dev run plan, without required lock or hardened profile
HandlerDiagnosticsUnavailable	Unavailable or existing destination	Choose a new file in an accessible directory; no existing file is overwritten
HandlerDeclaredContractDrift	Generated handler constants differ from source	Review and adjust grants, handles and signature in handler and test; business code is not overwritten
RuntimeFailure (return type mismatch)	Returned value violates gives	Fix the return path and type, then recompile; do not accept null as typed success

This page lists the main diagnostics and user-facing errors.

How to read this page

Each row gives the code or error family, the likely cause, and the recommended action. For more detail, see the CLI reference or the troubleshooting guide.

Sources, audit and startup

Code	Cause	Action
SourceRefMismatch	Corresponding source missing	Supply all modules with repeated --source options, preserving directories
SourceRefAmbiguous / SourceArtifactDuplicate / SourceArtifactUnused	Ambiguous, duplicate or unrelated sources	Supply exactly the referenced sources
TraceAuditDigestMismatch	Artifact differs from the seal	Preserve evidence and investigate; do not regenerate the seal to hide the mismatch
ToubaServePreflightFailed	Startup refused	Read detailed diagnostics and paths
ToubaServeProductIdentityPathInvalid	Identity path outside project or invalid	Place the file under --project-root and correct --identity
AgentCapabilityNotAllowed	Selected capability absent from the agent's uses	Correct the decision; expand authority only if legitimate
InvalidTextLiteral	Invalid escape or raw control character	Use JSON escapes, including \n and \\

Compilation and Semantics

Code or family	Likely cause	Action
UnknownReference	Call or reference not found	Check the name and declaration
MissingExplicitCallArgument	Required argument missing	Add with <name> as <expression>
UnknownCallArgument	Unknown argument name	Match the name after with to takes
DuplicateCallArgument	Same argument provided twice	Remove the duplicate
DuplicateResultBinding	into binding already used	Choose a distinct name
DuplicateLocalBinding	bind name already used in the graph	Choose a distinct local name
UnsupportedModuleConstantExpression	define contains neither a scalar literal nor a qualified enum member	Use a supported value or move the computation into a function
UnreachableStatement	Statement placed after a terminal return (give, stop, or an if whose branches all terminate)	Move the statement before the return, or keep one give per path
InvalidBranchCondition	Non-boolean if condition	Produce a Boolean
EnrichedAgentCallBlocked	A with / into call targets an agent without a resolved interface	Declare takes / gives and supply the source context, including imported modules
AgentCallerNotAllowed	Agent call not authorized	Fix callable_by
UnsupportedTriggerEventKind	Trigger from an unavailable family	Use on schedule "..."
UnsupportedTriggerTargetKind	Trigger targeting an unavailable target kind	Use runs strategy <Name>
MissingTriggerLimits	Trigger without limits block	Add max_runs_per_day and timeout_ms
MissingTriggerLimit	Required limit missing	Add the missing limit
InvalidTriggerLimit	Non-positive or non-integer limit	Provide a strictly positive integer
UnknownTriggerTarget	Target strategy absent	Declare the targeted strategy
InvalidTriggerArgument	Trigger argument is not a literal or define	Use a literal or module define

Expressions

Code or family	Likely cause	Action
InvalidExpressionOperandType	Operator applied to the wrong type	Check Text, Boolean, Int, Float
UnknownExpressionField	Field absent	Check the local type
UnknownEnumVariant	Unknown enumeration member	Use a declared member of the qualified type
DuplicateEnumVariant	Repeated enumeration member	Keep each member name unique
StaticExpressionDivisionByZero	Detectable division by zero	Fix the denominator
AstError	Syntax error or unsupported construct	Inspect the local position and hint; check indentation and clauses instead of accepting a recovered tree

Runtime, Tools, Manifest, and Secrets

Code	Likely cause	Action
ToolBindingManifestMissing	Manifest absent	Supply the manifest
ToolBindingMissing	Binding absent for the tool	Add the entry to the manifest
ToolCapabilityNotGranted	Required capability absent	Add the grant if legitimate
SecretReadGrantMissing	Secret without suitable grant	Fix the binding
SecretRequiredButNotBound	Handle absent from binding	Add the handle
SecretNotResolved	Secret unresolved	Supply the secrets file with env, dotenv, or touba_store source
SecretHandleRevoked	Handle explicitly revoked in the secrets profile	Reactivate the handle if legitimate or choose a suitable secrets profile
SecretHandleExpired	Handle expired according to the secrets profile	Renew the value and update profile expiration
SecretNotGrantedToAgent	Agent not authorized to use the handle	Fix the agent scope
ToolInputSchemaInvalid	Invalid tool input	Align input with takes
ToolOutputSchemaInvalid	Invalid handler output	Fix the handler or gives
OptionalValueAbsent	Direct AIR tries to extract an absent value	Recompile and extract only inside if present
OptionalValueInvalid	Invalid optional envelope or type	Preserve explicit presence/absence and the declared type, without implicit null
ToolPayloadConstraintViolation	payload_constraints violated	Fix input, handler output, or manifest constraint
ToolHandlerTimeout	Handler too slow	Fix the handler or timeout
AgentDecisionProviderUnavailable	Agentic provider unavailable or raised an exception	Check provider module and dependencies
AgentDecisionProviderTimeout	Agentic provider too slow	Fix provider or adjust --agent-decision-provider-timeout-ms
AgentDecisionProviderSchemaViolation	Provider response outside contract	Return a decision conforming to touba-agent-decision-v1
AgentDecisionProviderBudgetExceeded	Provider call budget exceeded	Increase --max-provider-calls if justified
AgentDecisionProviderRetryLimitExceeded	Provider retries exhausted	Fix provider cause or adjust --agent-decision-provider-max-retries
AgentProviderObservationsBudgetExceeded	Observations too large for provider context	Reduce observations or use opaque provider-side references
AgentCapabilityDescriptionRequired	Capability exposed to a decision provider without a source description	Add an explicit description to every capability declared in agent.uses

Project Workflow

Code	Likely cause	Action
ModulePathNotCanonical	Source file outside project convention	Use src/<domain>/<module>.tb with module domain.module
ModulePathMismatch	Module name differs from source path	Align path and module line
ProjectRunProfileUnknown	Requested profile is absent from touba.project.json	Declare the profile or select an available pure, dev, or prod profile
EffectiveProjectMissing	Effective projection is absent in check mode	Run touba prepare --mode write --profile <profile>
EffectiveProjectDrift	Effective projection differs from its declared inputs	Review the changes, then regenerate with prepare --mode write
EffectiveProjectReadFailed	Effective projection is unreadable or not JSON	Remove the invalid derived artifact and regenerate it
ManifestDerivedDrift	Derived manifest was widened or edited outside project inputs	Declare authority in an explicit fragment and regenerate; do not edit the derived file
ManifestMissing	Project with tool but no manifest in check mode	Run touba prepare --mode write or create the manifest
ManifestBindingMissing	Tool declared without binding	Update manifest from AIR
ManifestGrantMissing	Expected grant absent	Review and grant explicitly if legitimate
ManifestSecretMissing	Expected secret handle absent	Add the handle, never the value
HandlerStubMissing	Expected handler stub absent	Generate the stub or supply the expected handler
ManifestBindingObsolete	Binding present for a removed tool	Remove the binding if the tool no longer exists
PackageSchemaMismatch	Invalid local package manifest or unknown schema version	Fix touba.package.json
PackageExportMissing	Import from a package to a non-exported declaration	Add the export or fix the import
PackageExportUnknownRef	Package export points to absent declaration	Fix exports or package source
PackageVersionIncompatible	Requested version differs from package version	Align touba.project.json and package
PackageAirProfileIncompatible	Package AIR profile incompatible	Use a package targeting touba-air-json-canonical-v1
PackageNameConflict	Local module or package conflict	Rename the relevant package or module
PackageAuthorityFieldForbidden	Package attempts to declare handler, binding, grant, secret, or permission	Remove authority from the package; authority stays in AIR, manifest, and runtime
PackageRegistryForbidden	Local package or project entry attempts to use a registry	Supply an explicit local manifest
RunPlanMissing	Expected run plan absent in check mode	Run touba prepare --run-plan <path> --mode write
RunPlanDrift	Run plan differs from expected artifacts	Regenerate with touba prepare --run-plan <path> --mode write
RunPlanSchemaMismatch	Invalid run plan version or shape	Fix JSON or regenerate the plan
RunPlanEntryUnknown	entry_ref absent from AIR	Fix --entry or Touba source
RunPlanAirMissing	Pointed AIR absent	Run touba prepare --mode write again or fix path
RunPlanManifestMissing	Required manifest absent	Produce manifest with touba prepare --mode write
RunPlanSecretsProfileMissing	Required secrets profile absent	Produce or supply the explicit secrets profile
RunPlanSupplyChainLockRequired	Strict profile without available lock	Supply or regenerate touba.lock.json
RunPlanSupplyChainDrift	Supply-chain lock incoherent with AIR, manifest, or handler	Regenerate lock after reviewing changes
RunPlanTriggerManifestMissing	Pointed trigger manifest absent	Supply the explicit trigger manifest
RunPlanLimitInvalid	Invalid run limit	Use a supported positive limit
RunPlanSensitivePayloadForbidden	Payload, prompt, or secret placed in run plan	Remove these values and supply them through the intended channel
BindingFragmentReadFailed	Binding fragment unreadable	Fix path or JSON
BindingFragmentSchemaMismatch	Fragment outside touba-binding-fragment-v1 schema	Fix schema or regenerate fragment
BindingFragmentUnknownTool	Fragment targets a tool absent from prepared AIR	Fix tool, import, or local package
BindingFragmentDuplicateBinding	Same binding repeated by fragment	Keep one binding source
BindingFragmentConflictingBinding	Two fragments diverge for same tool	Resolve explicitly before composition
BindingFragmentMissingGrant	AIR-required grant absent from fragment	Add the grant to the fragment
BindingFragmentMissingSecret	AIR-required secret absent from fragment	Add the secret handle to the fragment
BindingFragmentMemoryAccessMissing	Required memory access absent from fragment	Add memory access explicitly
BindingFragmentConstraintInvalid	Invalid payload constraint	Fix payload_constraints
BindingFragmentAuthorityFieldForbidden	Fragment attempts to grant caller, scope, policy, or security status	Remove authority from the fragment
BindingFragmentNotAssembled	touba run receives a fragment instead of assembled manifest	Run touba prepare --binding-fragment ... and supply touba.manifest.json
ResourceBindingsReadFailed	Resource bindings file unreadable	Fix path or JSON
ResourceBindingsSchemaMismatch	Resource bindings outside touba-resource-bindings-v1 schema	Fix or regenerate artifact
ResourceBindingUnknownResource	Binding targets a resource absent from prepared AIR	Fix reference or import
ResourceBindingUnsupportedKind	Family not supported by resource bindings	Use memory_backend, event_source, or decision_provider
ResourceBindingMissing	Required logical resource has no active binding	Supply a binding or disable requirement
ResourceBindingInactive	Binding explicitly inactive	Activate binding or choose another profile
ResourceBindingSecretMissing	Required secret handle absent from binding	Add the handle, never the value
ResourceBindingGrantMissing	Required grant absent from binding	Add grant if legitimate
ResourceBindingScopeMissing	Owner without compatible memory scope	Fix memory_scopes in Touba source
ResourceBindingPayloadForbidden	Raw payload or secret value in binding	Replace with handle or host reference

Skill Packs

Code	Likely cause	Action
SkillPackRefInvalid	Invalid pack or resource ref	Use skill_pack:<namespace>/<skill-id> or resource:<skill-id>/<name>
SkillPackResourceKindInvalid	Unsupported resource type	Use procedure, reference, example, template, sample, or script
SkillPackResourcePathInvalid	Missing, absolute, escaping, or non-file path	Keep a relative internal pack path
SkillPackDigestMismatch	Digest differs from content	Update digest after reviewing the file
SkillPackAuthorityFieldForbidden	Pack attempts to declare handler, command, grant, secret, scope, or caller	Remove authority from the pack; authority stays in Touba and manifest
SkillPackScriptExecutionForbidden	Script treated as executable by the pack	Keep script as a resource and go through a Touba tool
SkillPackExecutionLinkUnauthorized	Link to capability absent from agent.uses	Add capability to the right agent or remove link
SkillPackBudgetExceeded	Hints, activation, or model input exceed budget	Reduce pack or explicitly increase budget
SkillPackSensitiveContentForbidden	Active content contains secret, raw payload, full prompt, or raw memory	Replace with handle, summary, or host reference
SkillPackActivationUntraced	Active pack without observable activation event	Fix host or run trace
SkillPackExecutableConfusion	skill_pack:* chosen as executable capability	Choose a Touba skill or tool declared in uses

Project Server, Tests, and Identity

Code	Likely cause	Action
ToubaServeUnauthorized	Missing or invalid bearer token	Reconnect the project with the active server token
ToubaServeIdentityPermissionDenied	Valid session without permission for the route	Request the required role or assignment
ToubaServeSandboxTargetNotFound	Target absent from project AIR	Refresh and select a compiled target
ToubaServeSandboxExternalEffectsRejected	Runtime-only mode used for a target that can call an external tool	Explicitly authorize declared effects for this test
ToubaServeSandboxSecretsMissing	Required secrets profile is absent	Configure touba.secrets.dev.json or touba serve --secrets
ToubaServeSandboxDecisionRequired	Run suspended for a human decision	Submit the associated decision and resume the session
ToubaServeSandboxCheckpointNotFound	Resume checkpoint is absent or expired	Refresh the session and rerun when needed
ToubaServePendingHumanRequestNotFound	Human request already handled or unknown	Refresh decisions before responding

Authoring and Changes

Code	Likely cause	Action
ToubaServeElementAuthoringInvalid	Incomplete or out-of-contract creation intent	Fix fields for the selected primitive
ToubaServeElementAlreadyExists	A declaration already uses that name in the module	Choose a distinct name or edit the existing element
ToubaServeElementDescriptionRequired	Capability created without an explicit description	Add a description suitable for agentic routing
ToubaServeElementResponsibilityRequired	Agent created without an explicit responsibility	Describe what the agent is accountable for in responsibility
ToubaServeElementReferenceUnknown	Missing uses, callable_by, scope, or target reference	Select a reference declared in the module
ToubaServeElementCrossModuleReferenceRejected	Implicit cross-module reference	Declare the import in source before proposing the relation
ToubaServeChangeSourceDrift	The file changed after proposal creation	Refresh the project and submit a new proposal
ToubaServeChangeProjectLocked	A multi-file transaction is already running	Wait for completion or recover the reported transaction
ToubaServeChangeRecoveryConflict	Recovery cannot determine a unique state	Inspect the transaction journal before another write

Deployment

Code	Likely cause	Action
ToubaDeploymentSupplyChainLockMissing	prod bundle without a supply-chain lock	Produce and validate touba.lock.json
ToubaDeploymentRawSecretRejected	Secret value detected in an artifact	Replace the value with a handle
ToubaDeploymentHandlerImplementation	Handler stub present in the prod profile	Implement and test the handler
ToubaDeploymentSourceRevision	Unvalidated source revision in the prod profile	Review and commit the expected changes
ToubaDeploymentInsecureTargetRejected	Remote target uses HTTP	Use HTTPS
ToubaDeploymentUnauthorized	Missing or invalid token	Supply the token through the declared variable
ToubaDeploymentRevisionNotFound	Requested revision is absent	Run touba deploy list
ToubaDeploymentRevisionCorrupt	Materialized artifact differs from its digest	Remove the target from traffic and restore a verified revision
ToubaDeploymentRollbackUnavailable	No previous activation is available	Explicitly activate a known revision
ToubaServeDeploymentTargetNotConfigured	Project server has no deployment target	Supply target options to the server

Agents, Memories, and Interactions

Code	Likely cause	Action
UnauthorizedAgentInvocation	Caller absent from callable_by	Fix authority
MemoryBindingMissing	Memory access without binding	Supply memory binding
MemoryGrantMissing	Memory grant absent	Add grant if legitimate
MemoryNotGrantedToOwner	Active owner without memory scope	Fix source scope
HumanApprovalRequired	Approval without decision	Supply explicit decision
InvalidHumanApprovalDecision	Unsupported decision	Use an accepted decision
UserInteractionRequired	ask without input	Supply user inputs
InvalidUserInput	Non-textual ask input	Supply a string

Parallelism and continuations

Code	Cause	Action
InvalidParallelContract	Invalid target, signature or parallel context	Declare a typed target from a skill/strategy and recompile the source.
ParallelInputTypeMismatch	An argument violates the target signature	Fix the input list or bindings; the group is refused before its first call.
ParallelItemLimitExceeded	Input is not a list or exceeds its bound	Check the type and process bounded batches; no silent truncation.
ParallelBranchLimitExceeded	Too many live branches, including nested groups	Reduce fan-out or review justified host ceilings without bypassing budgets.
ParallelUserInputRequired	ask lacks an occurrence-specific host answer	Supply a correlated answer; never reuse another branch's response.
ParallelJournalLimitExceeded / ParallelCheckpointLimitExceeded	Private journal or checkpoint exceeds its size bound	Reduce payload or group size; preserve the last valid checkpoint.
InvalidParallelCheckpoint / ParallelContinuationMismatch	Incomplete state or divergence from saved execution	Preserve the file and check the build, source and artifacts; do not hand-edit it.
ParallelOutcomeUnknown	Interrupted call with no demonstrated outcome	Reconcile with the effect journal and external service; never redispatch blindly.

Tool, provider, authority and budget errors remain visible: branch failure is not replaced by partial success. See Recovery and Budgets.

Package distribution

See package diagnostics. Author files use one package manifest; runtime context checks keep their SkillPack codes.

Approval constraints

Code	Action
InvalidHumanApprovalPolicy	Use valid static role, deadline and separation literals.
HumanApprovalExpirationMustTerminate	End every expiration path with give or stop.
HumanApprovalAuthorityRequired / HumanApprovalEvidenceRequired	Supply the trusted host adapter and an authenticated evidence reference.
HumanApprovalAuthorityUnavailable	Restore the identity service; the continuation has not been authorized.
HumanApprovalRoleRequired / HumanApprovalSignerConflict	Use a currently authorized, distinct signer.
HumanApprovalAttestationInvalid	Bind evidence to this exact request, run and decision.
HumanApprovalCheckpointIncompatible	Keep the original AIR and complete private checkpoint; do not invent missing authority state.
HumanApprovalStateLimitExceeded	The run has reached its bounded approval ledger capacity (10,000 requests and receipts).

State origin and installation

ToubaServeStateBuildMismatch requires the preserved originating build; ToubaServeStateProjectMismatch requires the original project location. Do not edit state identity to bypass either check. ToubaServeStateOriginInvalid / ToubaServeBuildIdentityInvalid indicate invalid provenance; verify the archive and backup. ToubaServeStateSnapshotRequired means a SQLite journal remains: stop writers and establish a consistent snapshot. ToubaStoreFormatIncompatible identifies an unrecognized stored format. InstallationBuildMismatch / InstallationArchiveConflict preserve the active installation on fingerprint conflict. InstallationInProgress means an exclusive lock exists; check its owner before intervention. InstallationPathUnsafe / InstallationPathsOverlap refuse linked or overlapping source/target directories.

Host policy and content checks

• ProjectConfigFieldUnknown: unknown project or configuration key. Contexts belong in configuration.contexts.
• ToolHandlerSandboxAccessDenied: the OS reported a denied access in the required sandbox. Review code paths and data grants/scopes without disabling isolation. An inaccessible module may also appear missing; that remains a loading failure rather than an invented permission diagnosis.
• EngineCapacityExceeded: the persistent JavaScript engine reached its request capacity. Wait for an active run to finish before retrying; this is not a process launch failure.

SkillPackSensitiveContentForbidden matches secret values resolved for this run and explicitly forbidden content categories. It is not a generic API-key pattern detector. Keep all secrets out of distributed package resources.

HandlerSandboxUnsupportedPolicy refuses a required sandbox on an unqualified backend. HandlerSandboxGrantMissing requires the grant matching the selected paths. HandlerSandboxPathInvalid requires an absolute existing interpreter and individual existing code_paths files. HardenedSandboxUnavailable means the actual host probe failed or the policy is not qualified; it never authorizes an unsandboxed retry.