Pairing Troubleshooting
Most pairing failures are one of the cases below. Wrong, expired, already used, and out of attempts look the same to the client (refused). The Core's audit log says which. Mint a fresh code with actana pair new unless the note says the code was not sent.
Expired code
Default TTL is five minutes. --ttl changes it. After expiry the session is dead. Re-mint; you cannot revive it.
Attempts spent
Five wrong guesses kill the session. A typo burns one. Re-mint.
Wrong fingerprint
The CA the machine presented is not the line pair new printed. On first contact the code is not sent. Stop. Wrong host, or a Core whose CA was rotated. Get the current fingerprint from a new pair new. Fingerprint.
Address already registered
The Panel already has a Core at that endpoint. It refuses before spending the code. Common after actana token regenerate. Remove the Core (Settings → Cores → Remove Core), then add it again with a fresh code. actana core pair replaces in place and does not need that step. Revoke and rotate.
Unreachable 8443
Nothing answered. The Panel must reach the Core's TLS port; the Core never dials the Panel. In compose the address is core:8443 on the compose network, not localhost:8443 on your laptop (the Core publishes no host port). On metal, host:8443 must be reachable from the Panel host. Confirm the daemon is up (actana status on the Core).
ACTANA_PUBLIC_HOST mismatch
The Core's server certificate covers the host it was set up for. Dial a different name, a second interface, or a tunnel, and you can match the fingerprint and still fail: the certificate does not cover that address. Use the host in ACTANA_PUBLIC_HOST (compose: the service name, usually core). Changing that value after pairing re-signs the server cert for the new name; clients still dial the old one until you point them at it or pair again.
Code spoken with 0, O, 1, I, or L
Those characters are not in the alphabet (ABCDEFGHJKMNPQRSTUVWXYZ23456789). They are not mapped to a neighbour. A 0 is a transcription error and spends an attempt if the rest of the shape is accepted as a code. Ask them to read it again, or mint a new one.
pair new without setup
this Core has no pairing material
Run `actana setup` — pairing needs a CA to sign against.
Installing is not activating. install.sh then actana setup. A container image mints material on first boot; you still run actana pair new inside it.
Pairing from a container
actana pair on the Core works via the image binary:
docker compose exec core actana pair new
docker compose exec core actana pair ls
docker compose exec core actana pair revoke <target>
You do not need actana on the host for that. Help (actana pair --help) works even on a machine that has never run actana setup.
