> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a2v2.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find the symptom you're seeing and the fastest fix — wrong answers, stuck sources, a missing widget, exhausted credits, and access problems.

Find the symptom you're hitting below and work through the fixes in order — they're
ordered from most to least common cause. Each one links to the page that covers it in
depth. For shorter how-do-I questions, see the [FAQ](/faq).

<Note>
  Most agent and answer issues trace back to one thing: a source that isn't **Completed**.
  That's always worth checking first.
</Note>

## My agent says it doesn't know, or gives the wrong answer

The agent answers from the sources in its knowledge base. When it can't find a match —
or finds the wrong one — work through these in order.

<AccordionGroup>
  <Accordion title="1. Confirm the source is Completed">
    Open **Expertise → Knowledge Base** and check the source's **Status**. Only
    **Completed** sources are used in answers — content that's still **Unprocessed**,
    **Processing**, or **Failed** is invisible to the agent. See
    [Manage & reprocess sources](/knowledge-base/manage-sources).
  </Accordion>

  <Accordion title="2. Add a closer-matching Q&A pair">
    If a relevant source is Completed but the agent still misses, the question wording
    probably doesn't match your content. Add a [Q\&A pair](/knowledge-base/qa) phrased the
    way a real customer asks — Q\&A is the most precise way to control an answer. Add a few
    variations if customers phrase it different ways.
  </Accordion>

  <Accordion title="3. Sharpen your instructions">
    If the answer is off-tone, off-topic, or guessing, refine your
    [instructions](/building/instructions) — set the persona, scope, and a clear fallback
    ("if you can't find the answer, say so — don't guess"). Save each change as a new
    version so you can compare or roll back.
  </Accordion>

  <Accordion title="4. Remove or update conflicting sources">
    A stale or contradicting source can outrank the right one. Update or
    [delete outdated sources](/knowledge-base/manage-sources#remove-a-source) — outdated
    content is the most common cause of wrong answers.
  </Accordion>

  <Accordion title="5. Re-test before customers see it">
    Verify the fix in the [Sandbox](/testing/sandbox), and check the answer cites the right
    source. To compare two full configurations, use the
    [Playground](/testing/playground).
  </Accordion>
</AccordionGroup>

## A source is stuck Processing or Failed

Adding a source runs background processing — read, chunk, and index. Large or
image-heavy files take longer.

<AccordionGroup>
  <Accordion title="It's been on Processing for a while">
    Large or image-heavy files take longer — give it a few minutes; processing runs in the
    background even for big files. If it stays stuck or turns **Failed**,
    [reprocess the source](/knowledge-base/manage-sources#reprocess-a-source) from its
    **Actions** menu (**⋯**).
  </Accordion>

  <Accordion title="A file source Failed">
    Reprocess it first. If it keeps failing, the file may not extract cleanly — scanned
    PDFs (images of text) extract less reliably than digital PDFs. Try a text-based version,
    or paste the key content as [Text](/knowledge-base/text) or a
    [Q\&A pair](/knowledge-base/qa). Supported file types are PDF, DOCX, and TXT — see
    [Upload files](/knowledge-base/upload-files#supported-files--limits).
  </Accordion>

  <Accordion title="A website source returned little or no content">
    The page may render its content with JavaScript, or hide it behind a login or cookie
    wall. Confirm the URL is public and reachable in a normal browser, then
    [reprocess](/knowledge-base/manage-sources#reprocess-a-source). If it still comes up
    empty, paste the key content as an
    [uploaded file](/knowledge-base/upload-files) or [Q\&A](/knowledge-base/qa). See
    [Add a website](/knowledge-base/website).
  </Accordion>

  <Accordion title="A YouTube source failed or returned no transcript">
    The video likely has no captions, or it's private/restricted. Use a public video with
    captions, or add the content another way. See [Add YouTube](/knowledge-base/youtube).
  </Accordion>

  <Accordion title="I changed the original content and the agent is out of date">
    [Reprocess the source](/knowledge-base/manage-sources#reprocess-a-source) — it
    re-reads, re-chunks, and re-indexes the latest version. For a website or YouTube
    source it re-fetches the current content at the URL.
  </Accordion>
</AccordionGroup>

## The chat bubble or widget doesn't appear

Both snippets from the [Embed/Install](/embed/install) screen need to be in place, and
your site's cache cleared.

<AccordionGroup>
  <Accordion title="Check the snippet placement">
    Confirm both snippets are present: the widget script in your `<head>` and the config
    (`window.A2V2WidgetConfig = { chatbotId: "..." }`) before `</body>`. Make sure
    `chatbotId` is filled in and that your site doesn't strip `<script>` tags. Copy the
    snippet directly from the [Embed/Install](/embed/install#option-2--chat-bubble-recommended)
    screen rather than retyping it.
  </Accordion>

  <Accordion title="Check the browser console">
    Open your browser's developer console on the page and look for errors. If your site
    enforces a strict Content-Security-Policy, allow the widget's font and script sources.
  </Accordion>

  <Accordion title="Clear the cache">
    Your site or CDN may be serving a cached copy of the page without the snippet.
    Hard-refresh the page, and clear any site/CDN cache after embedding.
  </Accordion>

  <Accordion title="Fonts or styling look off">
    The widget loads its own font and isolates its styles in a Shadow DOM, so it won't
    clash with your site. If a strict Content-Security-Policy is blocking it, allow the
    widget's font/script sources. See [Embed & install](/embed/install#troubleshooting).
  </Accordion>

  <Accordion title="I just need a link with nothing to install">
    Use the [Share Link](/embed/install#option-1--share-link) instead — a hosted page you
    can send anywhere, no code required.
  </Accordion>
</AccordionGroup>

## My agent stopped answering / credits are exhausted

Credits are checked the moment an agent tries to act. At a zero balance, agents stop
generating new answers — but nothing is deleted, and answering resumes as soon as
credits are available.

<AccordionGroup>
  <Accordion title="Confirm the balance hit zero">
    Open **Billing** in your organization settings to check your balance. If it's at zero,
    visitors see a notice that there aren't enough credits to respond, and voice messages
    show "Insufficient credits to transcribe this recording." See
    [Credits explained](/billing/credits-explained#what-happens-at-zero-balance).
  </Accordion>

  <Accordion title="Top up now">
    Use **Top Up Now** to add credits immediately, or wait for your plan credits to refill
    at the start of the next billing period. See [Auto-recharge](/billing/auto-recharge#top-up-manually).
  </Accordion>

  <Accordion title="Prevent it from happening again">
    Turn on [auto-recharge](/billing/auto-recharge) so A2V2.ai tops up automatically when
    your balance gets low — set a **Max recharges per month** cap to bound your spend. For
    agents customers rely on, this is the difference between staying online and turning
    real visitors away.
  </Accordion>

  <Accordion title="Credits dropped faster than expected">
    A premium model costs more per message than a standard one, and high traffic
    multiplies that. Check which model your agent uses on
    [Model & settings](/building/model-settings) and compare costs in the Sandbox model
    selector. Document processing and voice transcription also draw credits. Track spending
    on the [Usage](/analytics/usage) page.
  </Accordion>

  <Accordion title="I topped up but the balance looks the same">
    Use **Refresh Usage** on the Billing page to pull the latest figures. Top-up credits
    appear under **Top-up Credits** ("Remaining from recharges"), separate from your
    monthly plan credits. Some card payments need an extra verification step from your
    bank — the credits are added once that completes.
  </Accordion>

  <Accordion title="Auto-recharge stopped working">
    You may have reached your **Max recharges per month** cap, or a payment failed. If
    several payments fail in a row, A2V2.ai disables auto-recharge. Update your card in the
    [billing portal](/billing/checkout-and-portal), then re-enable it. See
    [Auto-recharge troubleshooting](/billing/auto-recharge#troubleshooting).
  </Accordion>
</AccordionGroup>

## A visitor can't access a gated agent

A public agent can be open, restricted to your CRM, or behind a paywall. The fix
depends on which mode it's in.

<AccordionGroup>
  <Accordion title="Confirm the agent is Public">
    On [Visibility & access](/embed/visibility), a **Private** agent is hidden to everyone
    but you. Switch it to **Public** when it's ready for real visitors.
  </Accordion>

  <Accordion title="Visitors are asked to identify before chatting">
    That's expected with the **Restrict** mode — only users from your CRM can use the
    agent, so visitors identify before the conversation starts and are captured as
    contacts. Switch to **Use for Free** if you want no-friction access. See
    [Visibility & access](/embed/visibility#public-access-modes).
  </Accordion>

  <Accordion title="A paying visitor can't get in after paying">
    On a [Pay for Access](/billing/paid-agents) agent, their **access duration** may have
    expired or their **message credits** may be used up. Check their status in the
    Subscriptions table. See
    [Paid agents troubleshooting](/billing/paid-agents#troubleshooting).
  </Accordion>

  <Accordion title="I enabled Pay for Access but nothing seems set up">
    Pay for Access is finalized **with the A2V2.ai team** — after you enable it, they reach
    out to set the price and duration. If you haven't heard back, contact
    [support@a2v2.ai](mailto:support@a2v2.ai).
  </Accordion>
</AccordionGroup>

## I can't do something / a button is disabled

Some actions are limited by your [role](/settings/members-and-roles) or your plan.

<AccordionGroup>
  <Accordion title="I can't change billing or plans">
    Billing changes — plans, payment method, and auto-recharge — are **Owner**-only. Ask
    your organization Owner. See [Members & roles](/settings/members-and-roles#the-three-roles).
  </Accordion>

  <Accordion title="I can't invite an Admin">
    Only the **Owner** can invite or promote someone to **Admin**. As an Admin you can
    invite **Users** only. See
    [Members & roles](/settings/members-and-roles#troubleshooting).
  </Accordion>

  <Accordion title="The invite button says 'Buy more seats'">
    You've used every team seat on your plan. Add the **Team Member**
    [add-on](/billing/add-ons) or upgrade your [plan](/billing/plans). Seat changes are
    handled by the Owner.
  </Accordion>

  <Accordion title="The Instructions or Playground screen asks me to switch displays">
    These are desktop features. On smaller screens you'll be asked to switch to a larger
    display. Open them on a desktop or a wider browser window.
  </Accordion>
</AccordionGroup>

## Processing or answers feel slow

<AccordionGroup>
  <Accordion title="A source is taking a long time to index">
    Large or image-heavy files take longer to process — this runs in the background, so you
    don't have to wait on the screen. Track status from the
    [source list](/knowledge-base/manage-sources). If it stalls or **Fails**, reprocess it.
  </Accordion>

  <Accordion title="Answers take a moment to appear">
    The agent streams its reply in real time — while it works, you may see it *thinking*
    and using tools before the final answer appears. Heavier premium models can take a
    little longer per answer than lighter ones; compare in the
    [Model reference](/building/model-settings#model-reference).
  </Accordion>
</AccordionGroup>

## Still stuck?

If none of the above resolves it, email [support@a2v2.ai](mailto:support@a2v2.ai) and
include your **organization name** and the **agent** you're working on.

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-question" href="/faq">
    Quick answers to common questions.
  </Card>

  <Card title="Manage & reprocess sources" icon="arrows-rotate" href="/knowledge-base/manage-sources">
    Track source status and retrain.
  </Card>

  <Card title="Credits explained" icon="coins" href="/billing/credits-explained">
    How credits work and what happens at zero.
  </Card>

  <Card title="Embed & install" icon="code" href="/embed/install">
    Add your agent to your site the right way.
  </Card>
</CardGroup>