Troubleshooting¶

When a task fails, test one layer at a time. A layer that passes is not the cause.

Test the Layers in This Order¶

Start at layer 1. Move to the next layer only after the current one passes.

Layer	Test	Where to look if it fails
1. Agent session works	Open New chat and choose the agent. The chat opens	The agent status in the agent list. It must show Idle. Then check the sandbox
2. Model works	Send "Reply with the word ready". A reply appears	Inference providers status and the sandbox Default model
3. MCP tool works	Ask for one simple operation with one MCP tool. The tool result appears	MCP connections status and the sandbox tool list
4. Secret works	Ask for one small read-only call to the service that uses the secret	The hosts on the secret
5. Network access works	Ask the agent to fetch one page from an allowed host	Lens → Runtime telemetry → Network
6. External app works	Finish the OAuth sign-in, then ask for one simple operation in the app	The MCP connection status, or the OAuth secret status. It shows Degraded when the token refresh fails
7. Combined task works	Run the full task	Lens → Traces

Do not put an app username and password in agent instructions. Use the OAuth flow or a secret.

Symptom	Fix
The workspace shows Provisioning	Wait. Only a workspace in the Ready state works
Workspace provisioning failed	Select Retry provisioning
The agent shows Progressing, or the chat shows Starting agent...	The agent installs its packages. Wait for Idle. A change to the sandbox shows Progressing again
No agent is ready for chat	Create an agent, or ask a workspace admin to share one with you. See Share an agent
Select at least one model to continue	In the sandbox Models step, add a model and choose a Default model
No inference providers are configured	Select Open provider setup, add a provider, then refresh the catalog. Your draft stays
The Direct roles list in an invitation holds one role, Superadmin	Create a custom role first. See Users and invitations
This invitation is no longer available	The link expired, was cancelled or was used. Create a new link
You cannot create an API key	You need a Ready workspace with at least one agent
New schedule is disabled	The agent has no workflow. Ask the agent in chat to create one
Tenant Agent quota exceeded on a self-hosted install	The default limit is 2 agents for each organization. A cluster admin changes the quota

Symptom	Fix
The sandbox cannot switch on an MCP connection	The connection has not loaded its tool list. Wait, then open MCP connections. If the status shows Error, fix the authentication
Auto-discovery failed when you add an MCP connection	Enter the OAuth endpoints under Advanced
The agent cannot see a tool	The sandbox does not expose it. Switch the tool on in the sandbox
Chat asks you to Deny, Always allow or Allow once	The tool is Consent required. Choose one. A workflow run allows it automatically
A call fails and Lens shows Blocked	Add the host to the sandbox Allowed hosts
A call reaches the service but fails to sign in	Check that the secret hosts match the destination host. See Secrets for what AgentZ rewrites
A webhook call returns HTTP 400	The body is not valid JSON, or it does not match the workflow inputs. See Webhooks

Continue with FAQ.