Troubleshooting

When something’s off, the run detail page and the Tool uses view are the first places to look — they show the agent’s output and exactly which tools it called (even on failed runs). Failure cards give every member a safe summary and recommended action. Workspace admins can expand Technical details on the run page when the summary is not enough; viewers and operators do not receive raw runtime traces.

Common issues

A run stays queued while other agents are running. The instance has reached its execution limit. It starts automatically when a slot opens. Instance admins can raise the caps under Instance settings → Run queue. Queued sub-agents start before new orchestrator runs. A sub-agent can also wait behind that orchestrator’s own cap (default three). If no runs are active, check the API service logs and networking instead.

“LLM provider needed” / runs won’t start. The workspace has no Anthropic or OpenAI key. Add one under Settings → LLM Providers (Settings).

A connection-using agent fails with “no active connection”. The acting user hasn’t authorized that service, or the agent declared a provider/slot nobody has connected. Use the sidebar “Action needed → Connect” prompt or authorize it under Connections.

A run fails with an auth/401 error mid-way. The connection’s credential expired or was revoked (the connection is marked stale). Reconnect it under Connections.

An MCP server returns an error while closing a completed run. Agent Studio preserves the completed output and records the session-cleanup error as an operator warning. An error while opening the session or while the agent is still working remains a run failure and appears in the run details.

The agent narrates instead of acting, or truncates. A lower-tier model may hedge on tool use, or the response hit the token cap. Try a more capable model or raise max_tokens in model_settings. See Authoring agents → choosing a model.

A declared tools_module “couldn’t be loaded”. The sibling .py is missing from the repo, or it doesn’t export a non-empty tools = [...] list. See Sidecar Python tools.

“Improve the Agent” seems to do nothing. Usually a stale browser tab from a previous deployment — hard-refresh and retry. Confirm either your personal Tembo account or the workspace fallback account is connected in Settings. If work appears under the fallback account, connect your own Tembo API key before submitting again.

The wrong tool slug / tools don’t appear. Composio and Native MCP use different slugs for the same provider — make sure the agent’s tools: list matches the connection’s source:. See Connections.

Still stuck?

Check the agent and workspace dashboards for failure groups, and the Audit timeline for what changed and when. For instance-level problems, see Deploying & operating and the self-hosting guides.