Troubleshooting

This guide is organized by symptom. Find the issue you’re experiencing and follow the steps to resolve it.

---

Agent is slow or unresponsive

Symptom: An agent that used to respond quickly is now taking 15–30+ seconds to reply.

Cause: Almost always session bloat. As sessions accumulate history, each turn sends a larger context window to the model.

Resolution:

1. Open the agent → Sessions tab
2. Sort sessions by message count (descending)
3. Archive sessions with high message counts that aren’t actively needed
4. If all sessions are active, reduce session.maxContextTokens in the agent config (e.g., from 50,000 to 20,000)

After archiving, response times return to normal on the very next turn — no restart required.

---

Agent shows as “Offline” in the dashboard

Symptom: The agent’s status badge shows Offline. Chat and cron jobs are failing.

Causes and resolutions:

Cause	How to identify	Resolution
Container crashed	Check Activity log for error events	Contact support — the container will need to be restarted
Budget exhausted	Budget gauge shows 100%	Increase dailyTokenBudget or wait for midnight UTC reset
Gateway unreachable	Network issue on the server	Contact support with the agent ID and approximate offline time

Note

If an agent goes offline and you have cron jobs scheduled, those jobs will be skipped until the agent comes back online. They are not queued for retry — the next execution will be the next scheduled time.

---

Cron job is not running

Symptom: A cron job was supposed to fire at a scheduled time but there’s no record of it in the Activity log.

Checklist:

1. Is the job enabled? — Open the cron job and verify the Enabled toggle is on
2. Is the cron expression correct? — Verify the expression at crontab.guru. A common mistake is using 0 8 * * * but forgetting the job timezone is UTC, not local time
3. Is the agent online? — Cron jobs skip silently if the agent is Offline
4. Was the budget exhausted before the scheduled time? — Check the agent’s budget gauge for the day the job should have run

If all of the above check out and the job still didn’t run, check the Activity log for any cron.skipped events and contact support with the job ID.

---

Cron job runs but output is not delivered

Symptom: The Activity log shows the cron job executed successfully, but nothing arrived in Telegram/Slack/email.

Resolution:

1. Open the Activity log entry for the failed delivery — it will show the delivery error
2. For Telegram: Verify the bot is still connected (Settings → Notifications). If you blocked the bot or the connection expired, reconnect it
3. For Slack: Verify the bot is still a member of the target channel. If the channel was made private after connection, re-invite the bot
4. For email: Check spam/junk folder. Add notifications@agenfleet.ai to your contacts
5. For webhooks: Verify your endpoint is returning a 2xx response. AgenFleet marks delivery as failed if the endpoint returns 4xx or 5xx

After fixing the delivery issue, use Run Now on the cron job to re-trigger it immediately.

---

Agent output quality has degraded

Symptom: An agent’s responses are less accurate, relevant, or well-formatted than they used to be.

Common causes:

SOUL file drift — The SOUL file hasn’t been updated to reflect how the agent’s role or scope has evolved. Review the SOUL file and update the instructions, communication style, and scope sections to match current expectations.

Session context pollution — An older session contains off-topic or conflicting context that’s being injected. Archive the session and start a fresh one.

Model was changed — Check the agent’s configuration history (Audit Log → filter by “Agent config updated”) to see if the model was recently changed. Reverting to the previous model may restore expected quality.

Tool failure — If the agent’s quality depends on web_search and web search is returning poor results for certain queries, the agent may be reasoning from bad inputs. Check the Activity log for tool call success rates.

---

Memory search returning irrelevant results

Symptom: The agent references outdated or irrelevant memories at the start of conversations.

Resolution:

1. Reduce topK from 5 to 2–3 — fewer injected memories means less noise
2. Enable temporalDecay: true if not already on — this weights recent memories higher
3. Enable mmr: true if not already on — Maximal Marginal Relevance reduces redundant results
4. If the agent has a very large memory store with a lot of old irrelevant data, contact support to request a memory audit

---

Configuration change not taking effect

Symptom: You updated the agent config (model, tools, limits) but the agent seems to be using the old settings.

Explanation: Configuration changes take effect on the next turn or cron job run. They are not applied retroactively to an in-progress session or a currently-executing job.

If the change still isn’t reflected after the next interaction:

1. Verify the save was successful — the Settings tab should show the updated values
2. Check the Audit Log → Configuration changes to confirm the change was recorded
3. If the change isn’t in the audit log, the save may have silently failed — try again and look for validation errors

---

”Unknown field” error when saving configuration

Symptom: Saving agent config produces a validation error referencing an unknown field.

Cause: The configuration schema is strictly validated. Fields that don’t exist in the schema cause startup/save failures.

Common mistakes:

• failover (wrong) instead of fallbacks (correct) for model fallback
• Putting mmr directly under memorySearch instead of under memorySearch.query.hybrid
• Using raw IP addresses in bind settings instead of named options

Review the Agent Configuration reference for the correct field names and nesting structure.

---

Can’t connect Telegram

Symptom: Clicking the Telegram connect link opens the bot but the connection doesn’t register in the portal.

Resolution:

1. Make sure you clicked Send after /start in Telegram — just opening the chat isn’t enough
2. Wait 10–15 seconds and refresh the portal page
3. If still not connected, try disconnecting any existing connection (Settings → Notifications → Disconnect) and reconnecting from scratch
4. If the bot doesn’t respond to /start, the bot may be temporarily unavailable — try again in a few minutes

---

Getting more help

If you’ve worked through this guide and the issue persists, contact support:

• Email: support@agenfleet.ai
• Response time: within 1 business day (Foundation), within 4 hours (Operational), within 1 hour (Enterprise)

When contacting support, include:

• Your workspace ID (found in Settings → Account)
• The agent ID or cron job ID involved
• The approximate time the issue occurred
• What you’ve already tried from this guide