Failures and reset¶

Every failure below has one named repair. Brama does not route around a refusal: an alias has one route, and when that route or a dependency it needs refuses, the refusal is what the caller receives. Fix the named thing.

Credentials and permissions¶

Keep these identities separate:

GitHub release publisher: repository contents permission only for tagged releases;
host runtime: no GitHub publication permission and only its scoped Skarbiec grants;
bearer verifier: read only each dedicated client token item;
request-sign verifier: read only the named central HMAC items;
Brama workload: redeem only configured Brama capability IDs;
Weles reauthentication: one dedicated finite token, not a console token;
caller: one dedicated bearer and, when needed, one exact agent identity.

Credentials are rotated or revoked at their authority: GitHub, Skarbiec capability, or product-owned request-sign item. Never place them in committed env files, URLs, request examples, logs, screenshots, or provider payloads.

Alias state failures¶

Read the state with brama aliases or GET /v1/aliases. The four states and their repairs:

State	Meaning	Repair
`serving`	the alias's one route is present and authorized	none
`no_route`	the alias has no destination in the registry document	declare it with `PUT /v1/admin/routes`, body `{"alias","primary"}`
`capability_absent`	the route exists but its required capability is not authorized for this runtime	grant the capability named in the row's `required` field at Skarbiec, then re-read the row
`routes_file_invalid`	the registry document did not deserialize, for example because it carries an unknown top-level field	repair the document, or run `brama routes migrate` to keep only the known top-level fields and commit the validated result

A completion naming a declared alias that cannot serve is 503 alias_unserviceable, carrying details.state and details.route so the operator can see which route to repair. A completion naming an alias that was never declared is 404, whose details also carry state and route. In both cases the caller receives that answer; no other route is consulted.

Common failures¶

Missing `BRAMA_MODEL_ROUTER_CLIENT_IDENTITIES`¶

Observed: startup fails before binding the port.

Meaning: the verifier registry was not generated.

Action: launch through the packaged wrapper and confirm each verifier-only Skarbiec consumer can read its dedicated client token item. Do not create one shared token standing in for several clients.

Missing or invalid model aliases¶

Observed: startup reports that the exact alias set or matching provider capability is unavailable.

Meaning: central service policy and capability grants disagree.

Action: correct the central policy or the grant, then restart. Do not hand-edit a runtime alias around the policy.

Rejected route registry document¶

Observed: the registry document is rejected whole and aliases read routes_file_invalid.

Meaning: the document carries a top-level field outside schema_version, deployments and routes, or a route names a deployment that is not defined.

Action: run brama routes migrate as the registry owner to reduce the document to the known top-level fields and commit the validated result, then repair any route whose deployment is still undefined. The command prints the document it committed, so the fix is visible before the service is restarted.

HTTP 426 `secure_transport_required`¶

Observed: a remote request is rejected before auth dispatch.

Meaning: the peer is neither loopback nor an approved HTTPS terminator.

Action: use HTTPS and configure the exact terminator IP in BRAMA_TRUSTED_PROXY_IPS; do not trust arbitrary forwarded headers.

HTTP 401 `unauthenticated`¶

Observed: bearer or agent HMAC is missing, malformed, expired, or unknown.

Action: identify the intended client and agent, rotate or repair that exact credential at its authority, and sign the exact transmitted body.

HTTP 403 `forbidden`¶

Observed: identity is valid but not allowed for the requested model, agent, or path.

Action: inspect the central client binding and model allowlist, then widen that exact binding if the access is intended. Do not use a broader client's token.

HTTP 429 `provider_rate_limited` or `subscription_unavailable`¶

Observed: the route's provider or subscription refused the attempt, and that refusal reached the caller.

Action: inspect brama subscription list and the routing refusal for the unavailable members and the recorded window reopening time. Requests without an explicit billing target can use any eligible free member of the same provider pool; member names confer no rank. An explicit billing target remains restricted to that member, and exhausting the pool does not authorize a different route or provider. Repair the named grant or capacity cause rather than retrying an unchanged refusal indefinitely.

HTTP 503 `dependency_unavailable`¶

Observed: Skarbiec, the entitlements router, the catalog, or the configured provider is unavailable, and the request is refused with the dependency named.

Action: restore that named dependency. No substitute credential and no substitute storage is used in its place, so the refusal stands until the dependency is healthy. If the alias should point somewhere else while the dependency is down, an operator repoints it explicitly with PUT /v1/admin/routes and the change is visible in {"ok":true,"routes":<document>}.

Port unavailable¶

Observed: bind failure on the requested port.

Action: stop the conflicting process or select another loopback port. Do not bind an unauthenticated alternative interface.

Desktop first-use event delivery

Brama Desktop distinguishes saving first-use progress from sending its journey events. A failed step or completion write names its underlying error and does not claim success. Once completion is recorded, an event-delivery failure keeps the walkthrough closed and shows First use is recorded as complete, but Brama couldn’t deliver its journey events with the transport cause. Reading that completed attempt on a later launch does not reopen it because delivery failed. Reopening the walkthrough deliberately through Settings remains a separate reset operation.

Uninstall and reset¶

Stop Brama through the operator-owned host service manager.
Revoke runtime, verifier, request-sign, and GitHub publisher grants independently.
Retain or securely remove the journal according to operator policy.
Keep or archive the route registry document deliberately: it is the record of which alias pointed at which route.
Remove only the immutable staged release being decommissioned after its rollback window closes.
Remove the replaceable caches in Brama's state directory (perf.json, models-dev-cache.json) only when no Brama process uses them.
Provider vault resources remain owned by Skarbiec/entitlements policy; do not delete them as an uninstall shortcut.

To remove a single alias instead of an installation, use DELETE /v1/admin/routes with body {"alias"}; the answer is {"ok":true,"routes":<document>} and the alias afterwards reads 404 for callers.

Continue with CORE.md, INTEGRATIONS.md, the runbook, and the risk-labeled examples/.