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

# Troubleshooting

> Every error the agent prints, what it means, and how to fix it.

Start with the logs. The last line says why the agent stopped.

```bash theme={"system"}
docker logs cubit-agent
```

## Enrollment

> **enrollment refused (401): token\_unknown**
>
> The token was copied wrongly, or it belongs to another dataset. Copy it again, in full, from the dataset you are connecting.

> **enrollment refused (410): token\_expired**
>
> The token was not used within 7 days. Generate a new one and start the agent with it.

> **enrollment refused (410): token\_cancelled**
>
> The token was cancelled, or replaced by a newer one. Use the most recent token you generated.

> **enrollment refused (410): token\_used**
>
> An agent already used this token. Two common causes:
>
> * **You recreated the container without its volume.** The first agent enrolled, then lost its credentials. Generate a new token, start the agent with a persistent `/data` volume, and revoke the old agent in the dashboard.
> * **You never ran an agent with it.** Someone else did. The dashboard shows that agent. Revoke it, then generate a new token. See [A token you did not use](https://docs.concatflow.com/private-databases/guides/revoke-and-replace.md#a-token-you-did-not-use).

> **not enrolled yet, missing: CUBIT\_ENROLL\_TOKEN, CUBIT\_API\_URL**
>
> The agent has no credentials in its data directory, and no token to enroll with. Either this is the first start and the variables are missing, or the volume is not mounted. Mount the same volume the agent enrolled with, or enroll again with a new token.

> **cannot reach the Cubit API at [https://api.concatflow.com/agents/enroll](https://api.concatflow.com/agents/enroll)**
>
> The machine cannot open an HTTPS connection to `api.concatflow.com`. Check DNS and outbound port 443. See [Network requirements](https://docs.concatflow.com/private-databases/guides/network.md).

> **CUBIT\_API\_URL must use TLS (https\://, wss\:// or tls\://)**
>
> `CUBIT_API_URL` starts with `http://`. Use `https://api.concatflow.com`.

> **cannot write to /data**
>
> The data directory is read-only, or not writable by UID `10001`. Mount a writable volume at `/data`. A named Docker volume works out of the box.

## Database

> **refusing to serve: the database account can write**
>
> The account in `DATABASE_URL` has write privileges somewhere in the database. The rest of the line says where:
>
> ```text theme={"system"}
> refusing to serve: the database account can write (connection role is a superuser)
> refusing to serve: the database account can write (connection role has write privileges on tables in schema(s): public)
> ```
>
> Use a dedicated read-only account. See [Create a read-only account](https://docs.concatflow.com/private-databases/guides/read-only-account.md). Then restart the agent. It keeps its enrollment, so no new token is needed.

> **password authentication failed for user**
>
> The user name or password in `DATABASE_URL` is wrong. URL-encode special characters such as `@`, `:` or `/` in the password.

> **Name or service not known**
>
> The host in `DATABASE_URL` does not resolve from inside the container. Use an address the container can reach. A database on the Docker host itself is not `localhost` from inside the container.

> **unsupported database scheme**
>
> `DATABASE_URL` must start with `postgresql://`, `postgres://`, `mysql://` or `mariadb://`.

## MySQL 8 authentication fails

With agent `0.1.0`, connecting to a MySQL 8 account that uses the default `caching_sha2_password` plugin fails with:

```text theme={"system"}
RuntimeError: 'cryptography' package is required for sha256_password or caching_sha2_password auth methods
```

The fix ships in the next agent release. MariaDB is not affected.

## In the dashboard

> **The agent shows as Offline**
>
> No connection from this agent reaches Concatflow right now. Check that the container is running with `docker ps`, then read its logs. If it runs but stays offline, check outbound access to `agents.concatflow.com:443`.

> **Never connected**
>
> The agent enrolled but never connected to the broker. The usual cause is a firewall or proxy that allows `api.concatflow.com` but blocks `agents.concatflow.com`, or blocks WebSocket traffic.

> **Unknown status**
>
> Concatflow cannot check agent status at the moment. The agent itself may be fine. Try again in a moment.

> **Queries fail with no agent is connected for this dataset**
>
> No agent of this dataset is online. Start one, or [run two](https://docs.concatflow.com/private-databases/guides/high-availability.md) so one can take over.

## A revoked agent keeps logging errors

```text theme={"system"}
nats.errors.Error: nats: 'Authorization Violation'
```

The agent was revoked and can no longer connect. It keeps retrying until you remove it:

```bash theme={"system"}
docker rm -f cubit-agent
docker volume rm cubit-agent
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.