Agent troubleshooting
Use this guide to diagnose and fix common Agent issues.
Quick triage
- Confirm the model provider is enabled in Agents Config
- Confirm the Agent is connected to a valid model
- Confirm required tools are enabled
- Run a simple known-good test prompt
Common problems
| Problem | Likely cause | Fix |
|---|---|---|
| Agent does not respond | Provider/model is not configured correctly | Re-check API credentials, model name, and provider status |
| Agent fabricates values | Missing tool-use rule or no read tool enabled | Add strict tool rules and enable required read tools |
| Agent updates data unexpectedly | Write rules are too vague | Add explicit write constraints and refusal rules |
| Automation parsing fails | Output format changes between responses | Enforce a stable JSON schema in instructions |
| Self-hosted AI requests fail | Network egress restrictions | Follow Self-hosted AI features requirements |
| Agent Knowledge actions disabled | GEMINI_API_KEY is not configured | Set GEMINI_API_KEY in your environment and restart Budibase |
| Gemini store ingestion fails | Inaccessible (403 Forbidden) or not found (404) | Ingestion will fail immediately without retrying. Use 'Reset store' to recreate it. |
| SharePoint files not ingested | File size exceeds 100MB limit | Ensure knowledge source files are under 100MB for ingestion |
| Ingestion waiting for capacity | Gemini API rate limits reached | Budibase automatically defers and retries ingestion jobs with backoff. No action is required unless it persists for several hours. |
| Approved tool fails to execute | Inputs do not match the current resource schema, or another backend error occurred | Check the Activity timeline for the specific error. Confirm that field names, types, and constraints match the current table, automation trigger, or REST query schema. |
Debugging checklist
When behaviour is inconsistent:
- Reduce prompt complexity and retest
- Verify the tool list in the Agent context
- Add explicit examples of valid and invalid behaviour
- Test each instruction change against a fixed regression set
When to change instructions vs tools
Change instructions when:
- Behaviour is mostly correct but inconsistent
- Refusal or escalation logic needs tightening
Change tools when:
- The Agent cannot access required data
- The Agent has risky capabilities it should not have
Related guides
Updated 8 days ago
Did this page help you?