# Troubleshooting

> Finding out why a Continuum Local agent is offline or a request through it failed, with every error code the agent reports.

Start on the agent's host with
[`continuum-local check`](/foliums/blueprintr-user-guide/continuum/local-agent/configuration#the-check-command).
It tests the configuration, the state directory, the certificate roots, the
route to Blueprintr and a TLS handshake with each on-premise host, and says what
to change. It sends Blueprintr nothing beyond a TLS handshake, so it never
enrols, spends a token or claims work.

> [!CODETABS]
>
> === Debian, Ubuntu, RHEL
>
> ```bash
> sudo continuum-local check /etc/continuum-local/config.json
> ```
>
> === Windows
>
> ```powershell
> & "C:\Program Files\Continuum Local\runtime\node.exe" `
>   "C:\Program Files\Continuum Local\continuum-local.mjs" `
>   check "C:\ProgramData\Continuum Local\config.json"
> ```
>
> === Container
>
> ```bash
> docker run --rm \
>   -v /etc/continuum-local:/etc/continuum-local:ro \
>   -v continuum-local-state:/var/lib/continuum-local \
>   ghcr.io/blueprintr-io/continuum-local:<version> check
> ```
>
> === Bundle
>
> ```bash
> node continuum-local.mjs check ./config.json
> ```

On the Linux packages, run it with `sudo`: it then reads the service's
environment file and checks as the service account. On Windows, run it from an
elevated PowerShell, because only administrators and the service can read the
configuration folder.

## Logs

| Install | Logs |
| --- | --- |
| Debian, Ubuntu, RHEL, Rocky, Alma | `journalctl -u continuum-local` |
| Windows | `C:\ProgramData\Continuum Local\logs`. The service wrapper rolls the files by size and keeps eight |
| Container | `docker logs <container>` |
| Helm chart | `kubectl logs deploy/<release>-continuum-local` |
| Bundle | standard output and standard error, wherever your process supervisor sends them |

Each line is a JSON object. Warnings and errors go to standard error. The agent
masks each credential value it loaded before it writes a line, but host names
and addresses are not masked, so read a log before you send it anywhere.

A request the agent refuses is reported to Blueprintr with its code and does
not appear in the agent's log. Look for it where Blueprintr showed the failure.

## Error codes

When the agent cannot complete a request or a sweep, it reports one of these
codes. Blueprintr's message when **Verify** fails includes the code for most
of them, and a failed sweep shows the agent's own description on its results
page.

| Code | What happened | What to do |
| --- | --- | --- |
| `unknown_integration` | The agent has no entry for this integration in `config.json` and none sent from Blueprintr, or the entry's `provider` is not the connector the integration uses. | Send its credentials from the Continuum Local panel, or add its entry to the agent's `config.json`, then press **Verify**. Correct `provider` if it differs. |
| `host_not_allowed` | The integration's host is not in its `allowedHosts`. The same code covers an `http://` URL without `allowPlaintextHttp`, a redirect to another host with a credential in the URL or body, and a host sent from Blueprintr that resolves to an address the agent refuses. | Add the host to `allowedHosts` in the agent's `config.json`, or send the credentials again from the Continuum Local panel. See [Host not allowed](#host-not-allowed). |
| `credential_missing` | The agent has no credential for this integration, or the credential has no part with the name the connector needs. The message gives the part's name. | Send the credentials from the Continuum Local panel, or add them to the agent's `config.json` with the part names the panel shows. |
| `credential_unresolved` | The agent could not fill in the credential. A placeholder was left over, a part contains a line break or a character an HTTP header cannot contain, the system compressed a token response the agent asked it not to compress, or the agent no longer holds a sign-in token the system issued, usually after a restart. | Check the credential names on the agent match the Continuum Local panel, then press **Verify**. For a sign-in token the agent no longer holds, try again: a new one is fetched. If a placeholder was left over, upgrade the agent. |
| `upstream_unreachable` | The agent could not complete the request: DNS, a refused or reset connection, no route, more than three redirects, or a certificate it does not trust. | Check the base URL, and that the agent's machine can reach that system, then press **Verify**. For a certificate, see [Certificate errors](#certificate-errors). |
| `upstream_timeout` | The agent reached the system but it did not answer in time. | Check the system is healthy, then retry. |
| `deadline_exceeded` | The request's time ran out: the system did not finish responding, or the agent did not answer Blueprintr in time. | If the system was slow, check it is healthy and retry. If the agent did not answer, check that Continuum Local is still running and can reach Blueprintr, then press **Verify**. |
| `response_too_large` | The system's answer was larger than the request allows, the answer was too large to deliver in one poll to Blueprintr (about 1 MB), or a proxy refused a poll that contained only this result. | If the agent's log says Blueprintr refused a poll as too large, raise the request size limit on the proxy between the agent and Blueprintr. Otherwise, contact Blueprintr support with the integration and the time. |
| `unsupported_job` | This agent does not support this kind of request. | Upgrade the agent to the latest release, then try again. |
| `operation_not_allowed` | The agent's read-only guard refused the request. Nothing was changed. | See [Operation not allowed](#operation-not-allowed). |
| `discovery_not_configured` | A sweep was sent to an agent with no `discovery` block. | Add a `discovery` block to the agent's `config.json` and restart it. An agent older than 0.2.0 cannot report its ranges and needs upgrading first. |
| `cidr_not_allowed` | None of the ranges the sweep asked for is inside the agent's `discovery.cidrs`, or the agent lists no ranges. | Choose ranges inside `discovery.cidrs`, or add the range there and restart the agent. |
| `sweep_already_running` | The agent is already running a sweep, and it runs one at a time. | Start this one when the current sweep has finished, or cancel the current one. |
| `run_rejected` | Blueprintr refused the sweep's uploads, so the sweep stopped: the agent's credential was refused (HTTP 401), the first upload was refused, or the run was unknown, belonged to another agent or had already closed. | Start the sweep again. For HTTP 401, see [The agent is not accepted](#the-agent-is-not-accepted-http-401). |
| `agent_error` | Anything else. The message has the specifics, for example a `caFile` the agent could not read. | Act on the message. If it does not say what to change, contact Blueprintr support with the time and the agent's version. |

## Common failures

### The agent shows as offline

An agent counts as online when it has checked in within about ninety seconds.
When one has not been heard from for 15 minutes, Blueprintr emails the owners
and admins of the organisation that owns it, and of the team for a team's
agent. Each person gets at most one of these emails an hour, and none is sent
while Continuum Local is turned off in Blueprintr.

1. Check the service is running and the host is up.
2. Check that nothing blocks outbound HTTPS from the host to `blueprintr.io`
   and `agents.blueprintr.io`: a firewall rule, a proxy change, or a
   TLS-inspecting proxy whose root the agent does not trust. See
   [Network requirements](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements).
3. Run `continuum-local check`.
4. Read the agent's log for the reason it gives.

### Continuum Local is turned off in Blueprintr

The panel says so, and the agent's log shows HTTP 503 with a message that
says the same.
Blueprintr has turned Continuum Local off for every customer for a while, for
example during an incident. Nothing is wrong on your side. Agents keep their
configuration and reconnect on their own when it is turned back on, and no
sweep can start until then.

### The agent is not accepted (HTTP 401)

The log says Blueprintr rejected this agent's credential. The agent was revoked
or deleted in Blueprintr, or enrolled again on another machine. Create a new
agent in Blueprintr, put its token in `config.json` as `enrollmentToken`, and
restart the service. The new token re-enrols this install in place, so nothing
on disk needs deleting. Credentials sent from Blueprintr to the old agent are
removed and need sending again. Until then the agent retries every five
minutes.

### Enrolment fails

- On a first start, a `Fatal` line whose error ends
  `answered HTTP 401: Enrollment failed.` means the token was spent, expired or
  revoked: Blueprintr gives the same answer for each. Create a new token with
  **New token** in the Continuum Local panel, or for a revoked agent, create a
  new agent.
- An answer about the plan means the organisation that owns the agent has no
  active Enterprise plan. The token is not spent: once an owner renews the plan,
  restart the agent within the token's 24 hours.
- A token in `config.json` that Blueprintr refused on an agent that is already
  enrolled leaves the old identity in place, and the agent says so at start.
- A state directory the agent cannot write to is reported, with advice for
  the platform, before the token is sent.

### Blueprintr does not support the agent's protocol (HTTP 409)

Blueprintr does not support the protocol version this agent speaks. The log
says to upgrade to the latest release, and the agent retries every 30 minutes
until then. An upgrade keeps the configuration, the enrolled identity and any
integrations sent from Blueprintr, and needs no new token.

### The plan is inactive (HTTP 403)

The organisation that owns the agent no longer has an active Enterprise plan,
and the agent is paused. It keeps retrying and reconnects on its own once an
owner renews the plan.

### Certificate errors

Between the agent and Blueprintr, a failed certificate check usually means a
proxy that inspects TLS. `check` reports the certificate as not trusted and
shows the issuer. Give the agent the proxy's root certificate, in PEM form, as
`extraCaFile`.

Between the agent and an on-premise system, the request fails with
`upstream_unreachable`, and the message says whether the certificate is
self-signed, issued by an authority the agent does not trust, expired, not yet
valid, or does not name the host.

- For an untrusted certificate, set `caFile` on the integration to the
  certificate, or to the one from the authority that issued it, rather than
  turning certificate checks off.
- For a name mismatch, `check` lists the names the certificate contains. The
  integration's URL in Blueprintr and `allowedHosts` must use one of them.
- For an expired certificate, renew it on the system.
- Infoblox NIOS needs its certificate replaced first: see
  [Certificates](/foliums/blueprintr-user-guide/continuum/local-agent#certificates).

`allowInsecureTls` accepts any certificate from that integration's hosts. Use it
only when the system cannot present one the agent can verify.

### Host not allowed

`allowedHosts` must contain the host exactly as it appears in the
integration's URL in Blueprintr. A host name and an IP address for the same machine are
different entries. For an integration sent from Blueprintr, the host must also
fit `remoteCredentialScope`, and the address it resolves to is checked at every
connection. Add the host to `allowedHosts` in the agent's `config.json`, or send
the credentials again from the Continuum Local panel.

### Operation not allowed

The agent relays only requests it recognises as reads for that product.
Blueprintr's message says which case applied, and nothing was changed in any of
them.

| Blueprintr's message says the request | What to do |
| --- | --- |
| is not one of the connector's reads | The agent is probably older than the connector. Upgrade it to the latest release, then press **Verify**. |
| is not a read at all | Try upgrading the agent first. Only if the integration must change something in that product, set `"allowWriteOperations": true` on its entry in `config.json` and restart the agent. Blueprintr can never set it. |
| failed one of the agent's safety checks on the request itself | This is not a sign the integration needs write access, so leave `allowWriteOperations` off. If it keeps happening, contact Blueprintr support. |
| belongs to an integration configured from Blueprintr for a product the agent has no read rules for | Add the integration to the agent's `config.json` instead, or upgrade the agent. |

### Proxy problems

`check` shows the proxy it used and tells its failures apart from a firewall's:

| `check` says | Fix |
| --- | --- |
| the proxy wants a user name and password (407) | Write `proxy` as `http://user:password@host:port`, ideally behind `env:` or `file:` |
| the proxy refused the tunnel | Allow CONNECT to port 443 on `blueprintr.io` and `agents.blueprintr.io` |
| the proxy refused the connection, or its host name does not resolve | Correct the proxy's host and port |
| no answer within the timeout: a firewall is probably dropping the connection | The host has no direct route out. Set the proxy where the service reads it: see [Proxies](/foliums/blueprintr-user-guide/continuum/local-agent/network-requirements#proxies) |

An agent on Node.js older than 24 refuses to start with a proxy configured. Use
a package or the container, which include Node.js 24, or upgrade Node.js for the
bundle. If the agent's log says Blueprintr refused a poll as too large, a proxy
between them may limit request size: raise its limit for the Blueprintr hosts.