---
title: "Pairing Troubleshooting"
url: "https://control.actana.ai/docs/pairing/troubleshooting"
description: "What each pairing refusal means — expired, spent, wrong fingerprint, unreachable — and which ones never spent your code."
updated: 2026-09-01T09:03:08+00:00
---

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`](/docs/pairing/create-a-pairing-code) 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](/docs/pairing/how-pairing-works).

## 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`](/docs/pairing/cli-pairing) replaces in place and does not need that step. [Revoke and rotate](/docs/pairing/create-a-pairing-code).

## 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

```text
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:

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

## See also

- [How pairing works](/docs/pairing/how-pairing-works)
- [Mint a pairing code](/docs/pairing/create-a-pairing-code)
- [Redeem in the Panel](/docs/pairing/panel-pairing)
- [The CA fingerprint](/docs/pairing/how-pairing-works)