Troubleshooting

I don't see an agent on the AgentForce hub

The agent is probably disabled for your workspace. An admin can re-enable it from /admin/agents. If you're an admin, head there and toggle the agent on.

If the agent is enabled and still missing, refresh the page — the catalog uses Convex queries that should update live, but a refresh can clear stale state.

"This agent is unavailable" when I open a chat URL directly

You opened a URL like /agentforce/sales/chat for an agent that's been disabled in your workspace. An admin needs to re-enable it. Once it's enabled, the page works normally.

Agent's response feels generic — like it didn't read my docs

Two things to check:

1. Did the agent call search_kb? Look for a tool-call pill in the response. If it's missing, the agent answered from context alone.
2. If yes, did the search return what you expected? Click the pill to see the search results. If they're irrelevant, your question may have been too vague — re-phrase with more specifics.

A quick fix: ask the agent to explicitly search ("Search the knowledge base for our refund policy and quote it directly.").

I'm getting wrong info — the agent confidently said something untrue

The catalog agents try to ground answers in tools (knowledge base, contact lookup, integrations) and to admit when they don't know. But like all AI systems, they can hallucinate.

If you spot a wrong answer:

• Click the source pills to see what the agent actually retrieved. If the source contradicts the answer, the agent misinterpreted; you can flag this in feedback.
• Re-ask with explicit context ("According to our refund policy, what's the window for enterprise customers?") to anchor the answer.
• Don't act on the answer alone for high-stakes decisions; verify against the source.

A tool call errored

You'll see a tool-call pill with an error icon. Common causes:

• search_kb errored — Knowledge base may be temporarily unavailable; try again in a moment
• Integration tool errored — The integration may be disconnected or its credentials expired; check /settings/integrations
• search_org_contacts returned nothing — The contact may not be in your workspace's contact list; the agent will tell you and proceed without it

In most cases, the agent gracefully continues with the rest of its response.

Agent stopped responding mid-message

Refresh the page. The thread state is server-side, so refreshing won't lose your message — it'll resume where it left off, or you can re-ask. If responses consistently stop, the Mastra service may be having issues; check with your workspace admin or wait a few minutes.

Threads are missing after I refreshed

Threads are stored in Mastra's memory layer (Postgres) and shouldn't disappear. If a thread is missing:

1. Check you're in the right workspace — threads are per-workspace per-user
2. Check you're signed in as the right account — threads are private to the user
3. Look in the agent's thread sidebar — the missing thread may have a different title than you remember (auto-titles can shift on later edits)

If a thread is genuinely gone, contact support — that shouldn't happen.

I want to change an agent's personality

You can shape the agent's behavior turn-by-turn by giving it instructions in the conversation ("Use a more formal tone for this thread"), but you can't permanently change its base personality through chat alone.

Catalog agents have a fixed base personality, but admins can layer custom instructions on top — see Instructions. For full control over personality, build a custom agent: Creating agents.

Permissions error on /admin/agents

You're not an admin in this workspace. Only workspace admins can change the catalog's enabled/disabled state. Ask an admin to make the change, or get promoted to admin from the workspace member list.

Still stuck?

Reach out via Help. Include:

• The agent slug (e.g. sales, customer-support)
• The thread ID from the URL (the ?thread=... parameter)
• A description of what you expected vs. what happened

That information lets support reproduce the issue quickly.