Troubleshooting
The wizard writes nothing until its last step, so a refusal leaves you where you were. Find yours below, with what causes it and what to do about it.
If you have not connected a box yet, start at Connect your box.
The box is too old
Registering needs a box that speaks agent protocol version 15 or later. Version 15 is the release where the box lets the signed call that proves its secret come from a browser. On an older image that call dies before any handler sees it, and your browser reports that the same way it reports a machine somebody switched off. The wizard reads the handshake first so it can tell you the box is old instead of guessing.
Run a current image. Rebuild with
stackbone package and redeploy.
stackbone link holds the same floor, so the terminal refuses the same box.
The secret was not accepted
Two causes produce this same answer, and the box cannot tell them apart:
- The secret is not the one the container runs with. A copied trailing
space counts as a different secret. Check the value in the container's log
from its first boot, or the
HMAC_SECRETyou set on it. - Your computer's clock is more than five minutes off the box's. The signature carries the time your browser made it, and the box refuses anything outside a five-minute window in either direction. A drifted clock looks like a wrong secret. Check both machines.
The wizard saved nothing either way, so fixing the cause and trying again costs you one more click.
The box has a third answer you will see less often: no secret to check
against. You started that container without a signing secret of its own, so it
has nothing to compare yours to. Restart it with HMAC_SECRET set, then type
that value here.
The box was not told
After the box accepts the secret, the wizard tells it which installation it answers for. Only then does it register the deployment. This panel means the box confirmed the secret but could not record that identity.
The secret is not the problem here. The box confirmed it a moment earlier with the same value, so leave the secret and your clock alone.
When the box explains itself, the panel shows the box's own sentence, and that sentence names the cause. Most often the box cannot reach its own database, or the migrations never ran on that database. Fix that on the container, then submit again.
The wizard saved nothing. It registers nothing until the box records its identity, so a refusal here leaves no record behind.
Nothing came back
The browser does not say which of these it was, so check all three:
| Cause | How to tell |
|---|---|
| The box is not reachable | Open the address in a new tab. If nothing loads there either, the problem is the machine or the network, not Stackbone. |
| Mixed content | Stackbone runs over HTTPS, so the browser blocks a call to a box that does not. The address has to be https://. |
| The origin allowlist | An override replaces the box's allowed origins, it does not add to them. One that omits the Stackbone app fails the browser's permission check before your browser sends the request. |
That last one is easy to miss. If you set an allowlist on the box for a
frontend of your own, keep https://app.stackbone.ai on it.
When you cannot fix the network between your browser and the box,
stackbone link writes the same record
from a terminal that can reach it.
Something answered, but it is not a box
The address replied, and the reply was not a Stackbone handshake. A company site answers like this. So does a load balancer sitting in front of the wrong service. Check the address, including the port and any path your ingress strips or adds.
Replace the box
Open the wizard for an agent whose template already has a box and it warns you before writing anything, naming the address it will replace.
A template has one box, so this is never "add another". Finish the wizard and every installation of that template moves to the new address.
Rotate a secret on the same screen. When the secret you register differs from the stored one, Stackbone moves the old value into a rotation slot and signs with both for a while. Your traffic survives the gap between registering the new secret and restarting the container with it. Register an unchanged secret and the slot stays as it was.
You never see the wizard
Open an agent with no box and you land in Studio instead of the wizard when your role does not let you manage agents in the organization that owns the template. You may be browsing a different one: a template you installed from somewhere else belongs to whoever published it. Ask an owner there to register the box, or to change your role.
What's next
- Connect your box: the three steps, start to finish.
- CLI troubleshooting: problems with the command-line tool rather than with a box.