---
title: "When something goes wrong"
description: "The first steps when an Arbol application shows an error or doesn't do what you expect, the most common problems in each one and what to include when you ask for help."
---

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

# When something goes wrong

Almost every error in Arbol has a simple explanation: a role, an organization, a session that expired or a change someone else made at the same time. This page helps you sort it out calmly and, if you can't, ask for help with what's needed.

> **The patient comes first**
>
> If the error affects a patient who's waiting, look after them the usual way at your organization, such as by phone or at the front desk, and come back to the error afterwards.

## The first steps

It almost always says what happened and what to do.

What you see depends on both.

If you were saving, first check whether it saved.

For access, a role or a setting.

With the time, the application, the message and the reference.

1. **Read the whole message.** Arbol's messages say what happened and, almost always, what to do: "Sign in again", "Check the details and try again", «Elige otro horario» (pick another time). If the message includes a **reference**, write it down: it helps if you ask for help (see [below](#what-to-include-when-you-ask-for-help)).
2. **Check your role and your organization.** If you don't see a button or a page, your role may not include it: see [Roles and permissions](/en/get-started/roles-and-permissions/). If you work in several organizations, check which one is selected at the top of the side menu: everything you see belongs to it.
3. **Try once more.** Reload the page or repeat the action once. If you were saving something, such as an appointment or a change to a patient, and you don't know whether it went through, check before repeating it so you don't duplicate it.
4. **Ask whoever administers Arbol at your organization** if you need access, another role or a change to a setting.
5. **Write to Arbol's team** if none of that works. The channels are in [Get help](/en/get-started/get-help/).

## Common problems

Click a problem to see what to do. Each application also has its own page: [Raíz](/en/raiz/troubleshooting/), [Agenda](/en/agenda/troubleshooting/) and [Ámbar](/en/ambar/faq/). Agenda's and Ámbar's screens are in Spanish, so their messages are quoted in Spanish with a translation.

### Access and organization

Your role in that application doesn't include that page or action. Each application says it its own way:

- **Raíz:** "You do not have access to this section" or "You do not have permission to do this."
- **Agenda:** «No tienes acceso a esta página» (you don't have access to this page), with the role you need and yours.
- **Account:** "Your role doesn't allow this page" or "Your role doesn't allow this."
- **Ámbar:** «No tiene acceso a esta página» (you don't have access to this page) or «Su usuario no tiene permiso para esta acción» (your user doesn't have permission for this action).

**What to do:**

- See what each role allows in [Roles and permissions](/en/get-started/roles-and-permissions/). For Agenda, in [Who can do what](/en/agenda/roles/).
- If your role changed recently, sign out and back in.
- If you need it for your work, ask whoever administers Arbol at your organization for that role. Don't use someone else's session.

If you work in several organizations, for example at two clinics, everything you see belongs to the one that's selected. You notice because you can't find patients, agents or appointments you know exist, or because you see:

- **Raíz:** "The page you're looking for doesn't exist, has moved, or belongs to another organization." or "You don't have access to this organization".
- **Agenda:** «No tienes permiso para esta acción en la organización actual.» (you don't have permission for this action in the current organization).
- **Ámbar:** «Esta organización todavía no está habilitada» (this organization isn't enabled yet).

**What to do:** at the top of the side menu, click your organization's name, choose **Switch organization** in Raíz, **Change organization** in Account, **Cambiar de organización** in Agenda or **Cambiar organización** in Ámbar, and pick the right one. If you opened a link someone sent you, it may belong to another organization. More in [Sign in to Arbol](/en/get-started/sign-in/).

It's been a long time since you signed in. Each application says it like this:

- **Raíz:** "Your session expired. Sign in again."
- **Agenda:** «Tu sesión venció. Vuelve a iniciar sesión.» (your session expired; sign in again).
- **Account:** "Your session expired. Sign in again."
- **Ámbar:** «La sesión terminó o no está disponible. Vuelva a iniciar sesión para continuar.» (the session ended or isn't available; sign in again to continue).

**What to do:** sign in again with your email and password. Anything you hadn't saved may be lost: check it when you're back.

### The page, or what you saved

- **Raíz:** "We couldn't load this page.", with **Try again**.
- **Agenda:** «No pudimos cargar los servicios y profesionales; lo que ves puede estar incompleto.» (we couldn't load the services and professionals; what you see may be incomplete), with **Reintentar** (retry).
- **Account:** "We couldn't connect. Check your connection and try again."
- **Ámbar:** «No fue posible completar la operación» (the operation couldn't be completed).

**What to do:**

1. Check your internet connection: open another web page.
2. Click **Try again** or **Reintentar**, or reload the page once.
3. If the message says there are too many requests or that the service is unavailable, wait a few minutes before trying again.
4. If nothing changes, open another Arbol application. If none of them loads, write to Arbol's team. If only one page fails, note which one.

Sometimes an action fails at the last moment and the application can't confirm the result. Account says "The change may have gone through: check before repeating it.", and Ámbar, «El servicio encontró un problema. Si estaba guardando, revise el resultado antes de repetir la acción.» (the service ran into a problem; if you were saving, check the result before repeating the action).

**What to do:** before repeating, check whether it went through. Look for the appointment in the agenda or in the patient's record, reload the list or open the record. Repeat only if it isn't there. That way you avoid a double booking or a repeated message to the patient.

Several people work at the same time, and Arbol doesn't let one change overwrite another without a warning. Whoever saves first keeps their change, and the application warns whoever saves after:

- **Agenda:** «La disponibilidad o el registro cambió. Actualiza y vuelve a intentarlo.» (availability or the record changed; refresh and try again).
- **Raíz:** "Someone else changed this while you were editing. Reload it and make your change again."
- **Ámbar:** «Los datos cambiaron; revise el caso de nuevo.» (the data changed; review the case again).

**What to do:** close and reopen the record, or reload the page. See what the other person changed and, if it's still needed, make your change again. More in [Agenda's common problems](/en/agenda/troubleshooting/).

- **Agenda:** the agenda's **PDF** button doesn't show on a phone: use a computer or a tablet. If it says «Son demasiadas citas para un solo PDF» (too many appointments for one PDF), choose fewer days, one site or one professional. If the browser blocks the appointment slip's new tab, the slip downloads as a PDF instead. See [Print the appointment slip and the agenda](/en/agenda/print/).
- **Raíz:** if a conversation's report says "The PDF could not be generated. Try again.", wait a moment and click **Download PDF** again. See [Follow conversations](/en/raiz/conversations/).
- **In any application:** check your browser's downloads folder, and that it isn't blocking the application's pop-up windows.

These files contain patient data: keep and share them as [Safe use and patients' data](/en/get-started/safe-use/) explains.

### Agents and connections

An AI agent can get things wrong: it didn't have the information, the information changed, or it misunderstood. What matters is correcting it with the patient and keeping it from happening again.

**What to do:**

1. If the WhatsApp conversation is still open, take it over and correct whatever's needed with the patient. See [Handle a WhatsApp conversation](/en/raiz/take-over-a-conversation/). If it was a call, contact the patient the usual way at your organization.
2. For a messaging agent, leave feedback with **Improve response**, below the reply. The agent doesn't change until someone tests and approves the improvement. See [Improve replies](/en/raiz/improve-replies/).
3. Tell whoever tunes agents at your organization, with the **Agent design** or **Administration** role in Raíz, so they can review the instructions or the knowledge. See [Troubleshooting Raíz](/en/raiz/troubleshooting/).

The most common reasons:

- **The AI handed the conversation to your team.** The conversation says **AI paused**, and the transcript shows **Conversation handed to the team**, with the reason. The AI doesn't come back on its own: someone on your team must handle the conversation and turn the AI back on.
- **The agent reached its usage limit.** The reason says "The team continues because the agent reached its usage limit." Your team handles it meanwhile; tell whoever administers Arbol at your organization.
- **It's outside business hours.** On WhatsApp, outside business hours the AI doesn't reply and only sends the hours notice.
- **The agent is inactive or the channel isn't connected.**

**What to do:** follow the checklist in [Troubleshooting Raíz](/en/raiz/troubleshooting/) and, to pick a conversation back up, [Handle a WhatsApp conversation](/en/raiz/take-over-a-conversation/).

A **connection** is your organization's account in an external system the agents use, such as an insurer or a clinical system. If it says **Needs attention**, it stopped working and agents can't use it; in conversations, the tools that depend on it may show as **Failed**. In Raíz, a channel, such as a WhatsApp number, can also say **Needs attention**.

**What to do:** write to Arbol's team with the name of the connection or channel and your organization's ID: Arbol's team reviews it. Meanwhile, your team handles whatever the agent can't do, the usual way. More in [See the integrations](/en/account/integrations/) and [Manage your channels](/en/raiz/channels/).

### Appointments

Agenda doesn't hold a slot while you type: if someone else, or a Raíz agent, books it first, they get it. Agenda says «Ese horario ya no está disponible. Elige otro horario.» (that time is no longer available; pick another) or «Este servicio ya tiene a esa hora todas las citas que puede atender a la vez. Elige otro horario.» (this service already has as many appointments as it can take at that time).

**What to do:** in **Agendar** (book), Agenda searches again and shows the free slots without clearing the patient's details. Pick another one and confirm. If there are no slots, see [Agenda's common problems](/en/agenda/troubleshooting/) or [Book an appointment](/en/agenda/book-an-appointment/).

## What to include when you ask for help

With these details, whoever helps you can find the problem without asking you again:

- **When it happened:** the date and time, as exact as you can.
- **Where:** the application and the page, for example "Agenda › Pacientes".
- **What you did and what you expected** to happen, step by step.
- **The exact message**, copied as it is.
- **The reference**, if the application shows one (see below).
- **Your organization**, and whether it happens only to you or to other people too.
- **What you already tried**, such as reloading or signing in again.

### Where to find the reference

Some applications add a code to the error that identifies exactly what failed. Copy it as it is:

| Application | Where you see it |
| --- | --- |
| Agenda | At the end of the error message, in parentheses: «(Referencia …)». |
| Account | Below the error message: "Reference: …". It shows when the failure was on Arbol's side. |
| Ámbar | Below «No fue posible completar la operación»: open **Referencia para soporte** (reference for support) and copy the code. |
| Raíz | It doesn't show a reference. Give the exact time and the page. |

### What you should never send

- **Patient data:** names, ID documents, phone numbers or health data, nor screenshots that show them. Describe the case without them, for example "an appointment tomorrow at 9:00 for general medicine". If Arbol's team needs to find a record, they'll tell you how.
- **Passwords, verification codes or API keys**, neither yours nor your organization's systems'. They aren't needed to help you.

## For developers and systems

If one of your organization's systems or an AI agent uses Arbol's API or its MCP server:

- **Keep the request id.** Every response carries it in `metadata.requestId` and in the `X-Request-Id` header. Log it with every failure and send it when you report a problem. See [Responses and errors](/en/developers/concepts/responses-and-errors/).
- **Decide by the code, not the text.** Use `error.code` and `error.retryable`; on a `429`, wait the seconds in `Retry-After`. See [Retries](/en/developers/concepts/retries/).
- **Don't blindly repeat a write that got no response.** Its outcome is unknown: find out whether it was applied before sending it again. See [Handle errors and retries](/en/developers/guides/handle-errors-and-retries/).
- **Over MCP**, an error comes back as the tool's result, with the same error object. See [MCP](/en/developers/mcp/).
- **Keep patient data out** of your error logs and of the reports you send.

Source: https://docs.getarbol.com/en/get-started/when-something-fails/index.mdx