Troubleshooting

Find the symptom closest to what you see. Quoted text is the message VirtuAI shows, so you can search this page for it.

Most problems come from one of three places: a key missing from the workspace settings, a channel that isn’t turned on for the agent, or a change made in a different workspace from the one you are testing. Check those first.

Agent quality

The agent gives poor answers

Make the personality instructions clearer and more specific: the goal, the audience, the rules, and what to do when unsure.
Add or clean up knowledge base content. An outdated document produces confident, outdated answers.
Check that the knowledge base is attached to this agent, and that its documents finished processing.
Tune the model settings. A lower temperature gives more consistent answers.
Check that tool names, descriptions and expected outputs are accurate. The model decides when to call a tool from its description alone.

The answer stops mid-sentence

You see “Response was cut off — max output tokens reached”. The answer hit the agent’s Max Output Tokens setting. Select Continue to let the agent finish, or raise the setting on the agent. The new agent default is 1,000 tokens, which is short for long answers. See Limits.

The agent changed behavior after an edit

If versioning is off for the agent, every save reaches all its channels immediately. Turn on versioning on the agent page to work in a draft and publish when ready.
With versioning on, check that what you are testing is the published version, not the draft. The agent page says Unpublished changes when the two differ.
To go back, open History on the agent page and roll back to an earlier version.
Re-test in web chat first; it is the simplest channel.
Compare with earlier good conversations in Conversations.
Undo only the most recent change, and test again.

“Could not complete the request with the selected model”

The model provider returned an error. Try again, or pick another model. If it keeps happening:

Check that the provider’s key is in the workspace settings. An agent saves without it, but fails as soon as someone talks to it.
For Gemini or Anthropic on Vertex AI, the workspace needs VERTEX_AI_SERVICE_ACCOUNT_JSON and VERTEX_AI_PROJECT_ID, and the project must have access to the model you chose.
Check that the model is still offered by the provider. Providers retire models, and VirtuAI removes them from the list when they do.

“The daily usage limit for this agent has been reached”

A workspace budget with a block action has been reached (the message names the period: daily or monthly). New requests are refused until the period resets or an admin raises the limit in Budgets. A budget with a warn action lets the request through and says the limit has been exceeded.

Channels

The agent doesn’t answer on a channel

Check that the channel is turned on for the agent, and that you saved the agent.
Check that the channel’s keys are in the workspace settings, in the same workspace as the agent.
Check that the channel points at this agent’s URL from Integration URLs. Each agent has its own.
Check the channel’s verification. VirtuAI rejects requests it can’t verify, so a wrong auth token, signing secret or project number stops every message. See the next section.

See also the troubleshooting sections for WhatsApp, Google Chat, Slack and Telegram.

“Web chat is not enabled for this agent”

The agent’s Chat channel is off. Edit the agent, turn on chat, and save.

Webhook requests are rejected with 401 or 403

Each channel is verified with its platform’s own mechanism. When the check fails, the request is rejected:

Channel	Status	Fix
WhatsApp	403	The webhook URL in Twilio must be exactly the WhatsApp Webhook URL from Integration URLs, and `TWILIO_AUTH_TOKEN` in Settings must belong to the Twilio account that owns the number. See WhatsApp.
Google Chat	401	The Chat app’s Authentication audience must be Project number, and `GOOGLE_CHAT_PROJECT_NUMBER` must be the number of the app’s project. See Google Chat.
Slack	403	Save the agent with its Bot Token and Signing Secret before Slack verifies the URL, and check that the signing secret is from the same Slack app. See Slack.

Telegram doesn’t return an error: messages that don’t carry the webhook secret are ignored. Select Register Webhook again on the agent.

A voice connection without a valid integration key is refused when enforcement is on. Check that it sends a key from the agent’s workspace that hasn’t been revoked.

The wrong agent replies

The channel’s webhook contains a different agent ID. Copy the URL again from the right agent’s Integration URLs.

Long WhatsApp answers arrive as several messages

This is expected. WhatsApp replies longer than 1,600 characters are split into several messages.

Message	What it means	What to do
“Incorrect email or password”	The credentials don’t match.	Check the address you were invited with. An admin can reset your password from Users.
“Native login is disabled; use SSO”	The workspace signs in through your identity provider.	Use the single sign-on option on the sign-in page.
“Self-service signup is disabled. Please request an invitation.”	Accounts are created by invitation only.	Ask a workspace admin to invite you.
“Your account is not a member of any workspace. Please contact an administrator.”	The account exists but belongs to no workspace.	Ask an admin to add you to a workspace.
“SSO access is not enabled for this email domain”	Your email domain isn’t linked to a workspace’s SSO.	Ask your admin to check the workspace’s SSO configuration.
“No role mapping matched your groups; access denied”	SSO worked, but none of your identity-provider groups maps to a VirtuAI role.	Ask your admin to add a group mapping, or add you to a mapped group.
“Your email domain is not authorized for this workspace”	The workspace only allows specific email domains.	Sign in with an address in an allowed domain, or ask your admin to add yours.

An invitation link doesn’t work

“This invitation has expired”: invitations are valid for 48 hours. Ask your admin to resend it from Users.
“This invitation has already been used”: the account already exists. Sign in instead.
“This invitation link is not valid”: the link may have been cut by your email client, or the invitation was revoked. Ask for a new one.

Menus and actions are shown according to your role’s permissions. For example, Settings and Integrations need settings.manage, and the Agent Builder is available to workspace admins only. Ask an admin to check your role in Users and roles.

You see another team’s agents, or not yours

Check the workspace selector. Everything in VirtuAI belongs to a workspace, and nothing is shared between workspaces.

Knowledge base ingestion

A file doesn’t appear after upload

Only PDF, Word (.docx), Excel (.xlsx, .xls), CSV and PowerPoint (.pptx) files are ingested. Files with other extensions are skipped. Convert them to a supported format first; for example, save a .doc file as .docx.

A document shows as failed

Each document goes through uploading, processing, and then completed or failed. A failed document shows its reason next to it:

Reason	Likely cause	What to do
“Failed to extract text from .pdf file” (or another extension)	The file is damaged, password-protected, or a scanned image with no text layer.	Export a text-based version of the file and upload it again.
“No text content found after chunking”	The file opened but contained no readable text.	Check the file has real text, not only images.
“Failed to store embeddings”	A temporary failure while indexing.	Use Reprocess on the document. If it fails again, contact support.

New chunk settings don’t change existing answers

Changing a knowledge base’s chunk settings doesn’t reprocess documents already uploaded. Use Reprocess on each document to apply the new settings.

The agent doesn’t use the knowledge base

Check that the knowledge base is attached to the agent, and that its documents are completed.
Ask a question using the words your documents use, and check the agent’s worklog in Conversations to see whether it searched.
If results are too few or too loose, adjust the number of results and the score threshold in the knowledge base’s retrieval settings.

Tools

A custom tool times out or can’t connect

The agent receives an error such as “API call to … timed out after 30 seconds” or “Failed to connect to …”. Check that the endpoint is reachable from the internet, and raise the tool’s timeout (up to 300 seconds) or retry count if the API is slow. Test the tool from chat before the agent goes live.

An MCP tool says authentication failed, or access was denied

“Authentication failed for ‘…’ (HTTP 401). The user may need to reconnect their account.”: the connected account’s authorization lapsed or was revoked. Reconnect it; in web chat, open the agent’s tool list and reconnect the service under connected accounts.
“Access denied for ‘…’ (HTTP 403)”: the account is connected but lacks the permission the tool needs. Grant it in the external service.
“The tool ‘…’ is temporarily unavailable (HTTP 5xx from the MCP server)”: the external server failed. Try again in a moment.

If one MCP server fails, the agent’s other tools keep working.

The agent asks for approval before running a command

Before an agent runs a shell command in its execution environment, it asks the person in the conversation to approve. If nobody answers within 5 minutes, the request counts as denied, and a late answer shows “That approval request is no longer waiting (it may have timed out).” Ask the agent to try again.

Voice

Browser voice doesn’t start

Check that voice and the web voice widget are turned on for the agent. Otherwise the widget reports that web voice is not enabled for the agent.
Allow microphone access when the browser asks. If you blocked it earlier, re-enable it in the browser’s site settings.
Check the voice provider’s key in Workspace settings: GOOGLE_API_KEY for Gemini voices, or ELEVENLABS_API_KEY for ElevenLabs.

A voice message in web chat isn’t transcribed

Voice messages in web chat need a Vertex AI service account in the workspace settings. Without one, transcription is reported as unavailable.
A voice message can be at most 5 MB. Record a shorter message.
If no speech was detected, record again closer to the microphone.
If the browser reports that voice recording isn’t supported, update it or switch to another current browser.

Still stuck?

Contact support, and include the workspace, the agent ID, the channel, and the time the problem happened.