Troubleshooting

Start on the agent's host with continuum-local check. 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.

sudo continuum-local check /etc/continuum-local/config.json

& "C:\Program Files\Continuum Local\runtime\node.exe" `
  "C:\Program Files\Continuum Local\continuum-local.mjs" `
  check "C:\ProgramData\Continuum Local\config.json"

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

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.
`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.
`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.
`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.
`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.

Check the service is running and the host is up.
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.
Run continuum-local check.
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.

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

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.