Troubleshooting

Connecting

A target I expect isn’t listed. Targets are invisible without a grant. Ask an admin for access, or request it just-in-time.

Connection refused or times out. Check that the controller can reach the target’s host and port. Private hosts must be reached through a bastion — the controller rejects internal addresses as direct targets.

Host key verification failed. The target’s SSH host key changed since Tessera first saw it. This is expected after a legitimate rebuild; an admin can clear the pinned key on the target so the next connection re-pins it. If you didn’t expect a change, treat it as suspicious.

Writes are refused. Your grant is read-only, or an admin downgraded your live session. See Read-only sessions.

CLI and tokens

command not found: tessera-cli. ~/.local/bin isn’t on your PATH; add it (the installer prints the exact line).

token bound to another device. Tokens bind to the first machine that uses them — see Access tokens → If a token stops working.

401 on connect. The token expired or access was revoked — sign in again with a fresh token.

Sign-in

TLS certificate warning. The controller is serving a self-signed certificate. Front it with a reverse proxy that terminates TLS using a real certificate — see Install on a VM. Only pass --insecure to the CLI against a controller you trust.

An OIDC button is missing or errors. Check the provider’s issuer URL and that the redirect URI https://<controller>/oidc/callback/<identifier> is registered. Providers are retried on first use, so a provider whose issuer was down at startup recovers on its own. See OIDC.

A removed user can still sign in. OIDC only blocks at next login. For immediate offboarding (blocking the account and dropping live sessions) enable SCIM.

Operating the controller

/metrics returns 401. It is protected by TESSERA_METRICS_TOKEN; send it as a bearer token.

/metrics returns 404. No TESSERA_METRICS_TOKEN is set, so the endpoint is switched off rather than served without authentication. Set one and restart. See Metrics.

Sessions dropped after an upgrade. Upgrading restarts the controller, which ends active sessions. Upgrade during a maintenance window — see Backups & upgrades.

Some targets show as locked. Your license expired or you dropped below a tier, so targets beyond the new caps become read-only rather than deleted. Renew or upgrade to restore them — see Licensing.

Credentials can’t be decrypted after a restart. The encryption key changed or was lost. In production always set a stable TESSERA_ENC_KEY (the package stores it in /etc/tessera/tessera.secret) and back it up — see Configuration.