AGENTO
v1.1.0 · Documentation
Documentation/Operate and debug/Troubleshooting

Troubleshooting

2026-10-15·source 4bebed4·4 min read·24 / 27

You will learn: Isolate the failure before changing configuration.

Isolate the failing boundary in order

  1. Can compileConfig() accept the YAML with the required environment values? If not, fix the reported config path first.
  2. Can invoke() run the intended tool using a fixed input and mock HTTP response? If not, inspect input validation, mapping, and dependency paths.
  3. Can that direct call run against the staging API? If not, inspect auth, status codes, transport, and output schema.
  4. Does chat() choose that same tool and input? Only now investigate provider capabilities, descriptions, hints, and recall.
  5. Can the UI continue selection and confirmation with the same authorized session? Inspect expiry and state persistence.

Use the first-tool fixture as a known-good baseline, then add the failing feature. Changing the model while the request map is wrong obscures the problem.

Capture a useful reproduction

Record the config version, tool ID, redacted input, expected API shape, result status/error code, and operation metrics. Use debug: true for candidate and mapping diagnostics; do not include credentials in a bug report.

A compile error should reproduce without a model. A dependency error should reproduce from a small fixed API fixture. A routing issue needs the exact message and expected candidate. This separation makes an open-source issue actionable.

npm returns E404

Check installation and run npm view agento-runtime version dist-tags. An unavailable package or version is a registry/release issue, not a YAML or Node import bug. Do not silently install a similarly named package.

ROUTING_NO_MATCH for casual chat

Check:

assistant:
  conversation:
    enabled: true

If conversation is disabled, deliberate no-match behavior is an error by design.

If conversation is enabled but the model call fails, investigate the provider error instead of adding fake greeting tools.

Arabic request does not select an English tool

Check:

  1. routing model is configured;
  2. semantic recall is enabled;
  3. catalog size does not exceed recall limits;
  4. provider/model handles Arabic sufficiently;
  5. add high-value Arabic trigger hints for latency/cost optimization.

The lexical retriever already includes Arabic normalization, but lexical matching cannot translate arbitrary concepts by itself.

Model invents an argument

The runtime should reject undeclared/invalid fields. If a legitimate user concept has nowhere to go, add it to the tool schema. If it is a server-owned ID, resolve it through dependency/selection/reference instead of broadening the prompt.

needs_input includes a field the dependency should produce

Check the dependency map destination path. It must point to the parent input field exactly:

map:
  $.slot_token: $.slot_token

Also verify the dependency is declared on the correct parent tool.

Selection expires too quickly

Increase dependency/selection-relevant TTL deliberately. Remember that confirmation cannot outlive dependency data. Do not simply set enormous TTLs for data such as availability that is genuinely volatile.

AUTH_REJECTED

AGENTO is reporting your API's 401/403. Inspect token acquisition, expiry, scopes, caller-to-session binding, and downstream authorization rules. Do not add local JWT verification to “fix” an API that is correctly rejecting the caller.

AUTH_REQUIRED

Usually means a configured server API key is unavailable. Check the environment variable named in request.auth.env.

Redirect blocked

Fix the configured URL to the final canonical endpoint. Redirect following is intentionally disabled to avoid credential forwarding to another origin.

Tool works directly but chat() fails

Direct invoke does not require a model. chat() does. Check models.routing or provide a custom ModelAdapter.

MODEL_SCHEMA_VIOLATION

Common causes:

  • provider returned tool arguments outside the declared schema;
  • strict provider tool-schema subset does not support your advanced schema;
  • custom adapter returned malformed structured output.

Try a supported schema subset or adjust declared model capabilities rather than disabling runtime validation.

TOOL_OUTPUT_SCHEMA_VIOLATION

Your upstream API response no longer matches the declared contract. Decide whether the API changed or the schema was wrong. Do not remove the schema blindly if orchestration relies on those fields.

TOOL_CIRCUIT_OPEN

The upstream produced enough transient failures to open the per-tool circuit. Inspect upstream health. diagnostics() shows circuit state.

TOOL_EXECUTION_UNCERTAIN

Do not immediately clear the session and retry a payment/booking/delete operation. Query the backend using your idempotency key/business operation ID and reconcile first.

Session expires after deploy

Expected when config hash changes or TTL expires. Start a fresh flow. This prevents old pending operations from continuing under new mappings/policies.

Concurrent messages corrupt a flow in multi-instance deployment

Your custom SessionStore likely violates the full-transaction serialization contract. A plain shared Redis value without a renewable lock/fencing strategy is insufficient.