Troubleshooting

If something's broken, start here. The patterns below cover the most common issues teams hit, in roughly the order you'd encounter them while building.

My agent run failed

1. Open Execution History, filter to Failed, click the run.
2. The trace highlights the failing step and the error class.
3. Look at the step's inputs — placeholders may have resolved to null, an empty string, or unexpected JSON.
4. Look at the step's outputs so far — the bug might be upstream of the failing step.

Common error classes:

My agent gives the wrong answer

It ran successfully but the output is bad. Usually one of:

• Prompt doesn't include the context. Open the trace, look at the rendered system + user prompt for the failing step. Is everything you expected actually there? Placeholders that didn't resolve are a common silent failure.
• Wrong model. Smaller / cheaper models hallucinate or ignore instructions. Try a stronger model for that step.
• Knowledge base missed. If you're relying on retrieval, check the trace's retrieval section. Did the right chunks come back? If not, your chunks may not be matched semantically; rephrase or restructure your sources.
• Tool wasn't called. The model decided not to use the tool. Tighten the system prompt to make the tool's purpose unmissable.
• Tool was called wrong. The model fabricated arguments. Add examples to the tool description, or constrain with structured output.

Add the failing case to your evaluation dataset so it stays fixed.

My deploy "worked" but production is broken

• Check Monitoring for error spikes immediately after the deploy.
• Compare the deployed revision against the previous one (Versioning → Compare).
• Check that any new integrations referenced in the new revision are actually connected and authorized in this organization.
• Check that any new secrets ({{secret.X}}) exist in this organization.
• If your agent calls sub-agents, are those sub-agents themselves deployed?

If in doubt: roll back first, debug second. (Deployment)

My integration won't connect

• Re-read the integration's setup page (each integration in /guides/integrations has prerequisites).
• For OAuth integrations: is the redirect URL configured in the provider's app config?
• For API-key integrations: try the credentials directly against the provider's API to confirm they're valid.
• Check audit log for recent integration changes — a teammate may have rotated something.

My connector isn't responding

• Confirm the connector is Enabled in the agent's Connectors panel.
• Check Conversations — did the message arrive at all? If not, the issue is upstream (connector not subscribed to the right channel/event).
• Check Monitoring — did a run start but fail?
• For Slack/Teams: confirm the bot is invited to the channel and has the required scopes.
• For webhooks: confirm the connector's webhook URL is what the upstream provider is hitting.

"I'm being throttled" / 429s from the API

• Organization API has rate limits per plan. Settings → Usage shows current consumption.
• For evaluation runs over large datasets, throttle locally (the SDK supports concurrency control).
• LLM provider rate limits are separate; bursting evaluations can hit your provider before Fruxon.

My costs spiked

• Open Settings → Usage and group by agent / model.
• Open the offending agent's Monitoring tab and sort runs by cost descending. Inspect the top few traces.
• Common culprits:
  • A loop that doesn't terminate.
  • A retry burst on a flaky tool.
  • A model swap to a more expensive model that wasn't intended.
  • A flood of inbound traffic from a connector.
• Set a budget cap on the agent immediately (Cost & Budgets) while you investigate.

My traces show empty / weird placeholder values

{{input.foo}} resolved to nothing because:

• The caller didn't provide foo and there's no default.
• The parameter name is misspelled in the prompt vs the entry point.
• An upstream step returned null.

Add a default in the entry point, or branch on the empty case.

My evaluations look great but production is bad

The dataset isn't representative.

• Pull a sample of recent failing conversations and add them to the dataset.
• Re-examine your metrics: are they measuring what users actually care about?
• Check whether your dataset has stale assumptions (old prompts, old model versions, old expected outputs).

I can't invite a teammate

• Only Admins can invite (Team & Roles).
• Free / starter plans cap seats — check Settings → Billing.
• Pending invitations expire; resend if it's been a while.

I lost an API key

API keys are shown once on creation. If you lost it, you can't recover it — revoke it and create a new one. The old key continues to work until you revoke it.

When you need help

• The API reference covers every endpoint.
• The FAQ covers the most-asked questions.
• The glossary defines every term used in these docs.
• Email support@fruxon.com with the execution ID of the failing run — it lets us look at the exact trace.