Troubleshooting
Agent Not Triggering
Your agent is active but isn't running when you expect it to.
Check: Agent Status
Navigate to Agents and confirm the agent status is active. A status of paused, draft, or error prevents execution.
If the status is error, check the agent definition for configuration issues — invalid step parameters, missing required fields, or an unsupported product action name are common causes.
Check: Trigger Filter Conditions
Trigger filters use exact matching. A filter of priority eq p1 will not match an event with priority: "P1" (capital P). Check the Event Catalog for the exact field values published by the source product.
To test your filters, navigate to a recent execution of a related agent (like a system agent triggered by the same event type) and check the raw trigger event payload. Confirm the field values match what your filter expects.
Check: Agent Conditions
Conditions are evaluated after trigger filters pass. If your conditions reference client_context fields, the Context Builder must have a profile for the client. New clients with no activity may not have a context profile yet — the Context Builder builds profiles proactively on key events.
Use context: 'event' conditions first to confirm the basic trigger is working before adding client_context conditions.
Check: Bus Connectivity
The One Agents receives events from The One Bus. If the Bus is experiencing latency or an outage, events will be delayed. Check the The One Status page for any Bus or Agents runtime incidents.
Check: Execution Limit
If your agent has an execution_limit configured (max_per_hour, max_per_day, cooldown_minutes), it may be throttled. Check the Executions view for recent runs of this agent and look for limit_reached log entries.
Check: Deduplication
Events within a 5-minute window for the same agent are deduplicated. If you're testing by firing the same event rapidly, subsequent events will be suppressed. Wait 5 minutes between tests or retry from the Executions view.
Execution Failed
Your agent fired but an execution failed.
Check: Step Trace
Open the failed execution in the Executions view. The step trace shows exactly which step failed and the error message. Most failures fall into a few categories:
| Error | Cause | Fix |
|---|---|---|
product_api_error | The target product's API returned an error | Check product API status. Verify action name and parameters are correct. |
credit_insufficient | Monthly credit allocation depleted | Purchase a top-up pack or wait for next month's allocation |
ai_model_timeout | AI model call timed out (>30 seconds) | Retry the execution. If persistent, consider reducing prompt length or switching to a lighter model tier. |
invalid_template_var | A {{variable}} reference in a step couldn't be resolved | Check that the variable name matches a previous step's output_var, or that the event payload field exists |
approval_expired | Approval Gate timed out with on_timeout: deny | Review the timeout configuration and notify recipients |
action_forbidden | Product API rejected the action (permissions) | Verify the service integration key has the required permissions for this product action |
Check: Product API Availability
Product Action steps call other product APIs. If the target product (PSA, Defend, etc.) is unavailable, the step will fail. Check on_error in the step config — continue means the execution proceeds, fail means it stops.
Check: Variable References
Template syntax like {{classification.priority}} requires that:
- A previous step defined
output_var: "classification" - That step completed successfully (not skipped or errored)
- The field
priorityexists in the step output
If a step with on_error: continue failed or was skipped, its output_var will be empty — subsequent steps referencing it will fail with invalid_template_var.
Credits Depleted Mid-Month
AI steps are failing with credit_insufficient errors.
Identify the Cause
Navigate to Credits → By Agent to see which agents are consuming the most credits this month. Look for:
- An agent with unexpectedly high run counts (may indicate a broad trigger filter firing on high-volume events)
- AI steps using Premium or Expert tier that could be downgraded without losing meaningful quality
Immediate Options
- Purchase a top-up pack — Available in Hub Billing. Top-up credits are consumed before the monthly allocation.
- Pause high-volume agents — Pause the top credit consumers for the rest of the month if they're non-critical.
- Downgrade model tiers — If an agent is using Standard (20 credits) for a classification that could use Quick (5 credits), update the step.
Prevent Recurrence
- Add trigger filters to narrow the event scope of high-volume agents
- Review execution counts in the Executions view — if an agent is running 500×/month, it may be too broadly triggered
- Consider upgrading your subscription tier if you're consistently hitting the limit
Approval Gate Not Sending Notification
A workflow reached an Approval Gate but no notification was received.
Check: Notification Channel
Confirm the notify_channel and notify_recipients are correct in the approval gate step config. For SMS, the recipient must be a valid E.164 phone number (+15551234567). For email, a valid email address.
Check: Voice Configuration
SMS notifications from Approval Gates use The One Voice infrastructure. If your organization has not configured a Voice number, SMS delivery will fail silently. Navigate to The One Voice settings to verify your outbound number is configured.
Check: Execution Status
The execution should be in waiting_approval status. If it's failed or completed, the Approval Gate may have timed out (check expires_at in the approval record) or there was a delivery error before the gate.
Approval Gate Timed Out Unexpectedly
The approval was received but the execution resumed with the on_timeout default rather than the human decision.
Check: Timezone
Approval Gate timeouts are calculated in UTC. A 2-hour timeout set at 11 PM UTC will expire at 1 AM UTC. Confirm the expires_at in the approval record against the time the notification was received.
Check: Decision Submission
Approval decisions must be submitted via the Agents console or API before the expires_at timestamp. If the decision was submitted after expiry, it will be logged but the execution will have already applied the on_timeout default.
Template Clone Not Appearing
You cloned a template but don't see the agent in your Agents list.
Cloned agents start in draft status. In the Agents view, check that your status filter includes draft (it defaults to active in some views). Find the draft, review the configuration, update the recipients and any org-specific settings, then set status to active.