Direct answer
Tool and file-action errors are different from normal chat errors. The model can answer text while a client-side tool, workspace permission, patch format, or schema validation step fails. Test one tiny non-streaming text request, then one tiny tool definition, then the full agent workflow.
Private order, key, and balance details belong in the customer portal or support. Public docs can explain the diagnostic path, not reveal account-specific state.
Error phrases this guide covers
Search tools, logs, and support tickets do not always use the same wording. Treat these phrases as the same troubleshooting family before changing unrelated settings.
Fast check before changing everything
Run the smallest check that isolates the failing layer. If the small request works, the problem is usually the client configuration, hidden context, permissions, or advanced feature path rather than the whole account.
1. Plain non-streaming chat.
2. One tiny tool definition.
3. One tiny file create or edit action.
4. Full project context and larger agent task.Common causes
- The client exposes tools to the model but blocks file writes, shell commands, or workspace access at the UI permission layer.
- The tool schema is too large, malformed, duplicated, or not supported by the selected route.
- The assistant returns a patch, but the client rejects it because the target path is missing or outside the allowed workspace.
- Streaming or long context makes it harder for the client to parse the tool call reliably.
Fix steps
- Check the tool or IDE permission mode before blaming the model route.
- Disable all tools except one minimal test tool and run a tiny prompt.
- If file editing is involved, confirm the target folder is visible to the client and that the path is inside the project workspace.
- Retry non-streaming before enabling streaming tool calls or full project context.
Verify before retrying production traffic
- Confirm plain chat works with the same model and key.
- Confirm the client log shows a tool call attempt, not just a text answer about a tool.
- Check whether the file appears in the client workspace after the patch is applied, not only whether the model says it created it.
Use one small request first. Large retries can spend balance, hide the original cause, and create confusing logs.
Diagnostic decision tree
Work through these checks in order. The goal is to isolate the failing layer before editing unrelated settings or sending another expensive request.
| Check | Action | Pass result | Fail result |
|---|---|---|---|
| Minimal request | Run the smallest check from this page with the same key, endpoint shape, and one public model slug. | The account and basic route probably work; move to client settings, hidden context, tools, or retries. | Fix auth, base URL, balance, model slug, or current route health before testing advanced features. |
| Client final URL | Inspect the actual URL or provider profile the client sends, not only the visible settings field. | Continue with request body, model slug, payload size, and feature compatibility checks. | Correct host/base/full-endpoint confusion before changing keys or model families. |
| Balance movement | Compare dashboard balance before and after one tiny diagnostic request. | If charged and no answer arrives, collect the support packet before retrying large prompts. | If not charged, focus first on request rejection, wrong endpoint, auth, or client-side failure. |
| Feature isolation | Disable streaming, tools, images, file context, long history, and automation loops for one retry. | Re-enable one feature at a time until the failing layer is identified. | Keep the request small and do not use production retries as the diagnostic method. |
| Route health | Check Service Status and try a tiny prompt on one nearby public model row if your workflow allows it. | Use a documented fallback only if quality and cost are acceptable. | Wait, switch safely, or contact support with timestamps instead of hammering the failing route. |
Prevent it next time
Treat agent actions as a separate capability from text generation. Keep workspace permission, file visibility, tool schemas, and patch application logs visible to users before running larger repo edits.
Minimum support packet
Collect these details before opening support. This avoids exposing secrets while giving enough context to match logs and reproduce the public failure path.
| Field | Why support needs it |
|---|---|
| Timestamp | Use UTC or include timezone so logs can be matched accurately. |
| Endpoint path | Include /v1, /anthropic, or the exact client route shape involved. |
| Public model slug | Send the customer-facing slug, not a private key, upstream account name, or hidden route. |
| Exact error text | Include the visible tool creation failed message and any HTTP status shown by the client. |
| Minimal request result | State whether the tiny check on this page works with the same key. |
| Balance movement | State whether balance changed after the failed request or only after retries. |
| Client and feature flags | Name the tool, SDK, streaming setting, image input, tools, file context, or automation loop involved. |
When to contact support
Contact support when a minimal reproducible check still fails, when the dashboard history does not match what your client received, or when usage appears charged but no usable answer reached the client.
- Include timestamp, endpoint path, public model slug, exact error wording, and whether the same key works on a minimal request.
- Include whether the dashboard balance changed and whether the client retried in the background.
- Do not send secrets, full API keys, regulated data, or private production prompts in public support messages.
Open the support bot after collecting the reproducible details.
Related sources
Use these pages to verify the exact base URL, model slug, billing behavior, service status, or broader troubleshooting route before changing unrelated settings.