> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/troubleshooting.md).

# Troubleshooting

The problems administrators hit most often, and what actually causes them.

## The assistant does not know something it should

Work through it in this order: the cause is almost always earlier in the chain than it seems.

1. **Is the document in a collection?** Check [Collections](/en/for-administrators/knowledge-base/collections.md).
2. **Is its status Indexed?** Anything else means it is not searchable yet. **Failed** shows a reason on hover.
3. **Does a search tool cover that collection?** Documents are not searchable without one. See [Search tools](/en/for-administrators/knowledge-base/search-tools.md).
4. **Is the search tool switched on for this assistant?** Check its **Tools** tab.
5. **Can retrieval find it?** Use **Try it** on the retrieval tool under [Advanced](/en/for-administrators/knowledge-base/advanced.md) and search for a phrase from the document. If it does not come back there, the problem is retrieval, not the assistant.
6. **Do the instructions allow it?** An assistant told to answer only from its documents will refuse if retrieval returned nothing.

## The assistant gives outdated or wrong information

Nearly always an old document still in the collection. The assistant has no way to know which of two versions is current. It will happily quote either.

Remove superseded documents rather than adding newer ones alongside them. If you must keep history, use a [label](/en/for-administrators/knowledge-base/labels.md) such as `archived` and exclude it with a content filter on the search tool.

## The assistant invents answers

* Lower **Creativity** in the assistant's [settings](/en/for-administrators/assistants/settings.md).
* Be explicit in the instructions: *"Answer only from the documents available to you. If the answer is not there, say you do not know."*
* Turn on **Show references** so users can check.
* Add a **No hallucination** check in [quality control](/en/for-administrators/quality/scenarios.md).

## A tool never fires

* **Is it switched on** for this assistant?
* **Does the model support tools?** The settings screen warns when it does not.
* **Is the description good enough?** This is the usual cause. The assistant chooses tools by reading **Description for LLM**. See [API tools](/en/for-administrators/tools/api-tools.md).
* **Are the argument descriptions clear?** The assistant has to work out what to put in them from the conversation.

## Someone cannot see a screen

They are not in a group whose role grants it. Open the user, check their **User groups**, then check what those groups carry. See [Roles and rights](/en/for-administrators/access/roles.md).

If *you* cannot see a screen described in this documentation, the same applies to you, or your plan does not include it.

## Someone cannot sign in

* Is the method they are using enabled in [Organization settings](/en/for-administrators/organization/settings.md)?
* Does the account exist with exactly that e-mail address?
* Did they ever complete the onboarding link? The platform does not e-mail those. You send them.

## No mail is arriving in the Inbox

* Check the channel's status under [Communication channels](/en/for-administrators/conversations/communication-channels.md). **Token revoked** means access has lapsed. Use **Reconnect**.
* Confirm an assistant is bound to the channel.
* Send a test message from an outside address.

## Replies look wrong when they arrive

The [mail template](/en/for-administrators/conversations/mail-templates.md) is the frame around the reply. Check that `body` appears exactly once, and read a test reply on a phone as well as a computer.

## Costs jumped

Open the [Token report](/en/for-administrators/reports/tokens.md) and break it down per assistant, then per model. Common causes: a new assistant went live, a search tool started returning much more context, or an expensive model is handling high-volume simple questions.

## Quality control went red

Read the actual answer before assuming the assistant broke. An over-strict check is the most common cause. **Exact match** in particular fails on harmless rewording. See [Runs and results](/en/for-administrators/quality/runs.md).

## When to contact your account manager

* Anything about hosting, data processing, compliance or contracts.
* A feature that appears to be missing or disabled for your organisation.
* Plan limits, invoicing, or capabilities you are unsure you have.
* A problem that persists after working through the above.