Troubleshooting

Common errors you will see in the console and how to recover from each.

CORS error on the Connect form

Message: CORS error: origin http://localhost:3000 not allowed, or "Could not connect" with a CORS preflight failure in DevTools.

Cause: The console's origin is not in the AcasoOS instance's ACASO_CONSOLE_ORIGINS env var.

Fix:

1. On the AcasoOS host, add the origin to the env:

   bash

   ACASO_CONSOLE_ORIGINS=http://localhost:3000,https://os.aca.so

2. Restart the AcasoOS server (make run, make run-agenthub). The value is read once at startup.

See Reference: Environment variables.

401 Unauthorized on the very first exchange

Message: Inline error on the Connect form, "Authentication failed" or ERR.AUTH.0001.

Cause: The long-lived key you pasted is wrong, revoked, or expired.

Fix: Mint a fresh key.

make mint-key USER_EMAIL=you@acaso.com USER_NAME="You"

Paste the new key into the Connect form.

ERR.AUTH.0012: the key's Application is not active

Cause: The Application that owns this key is suspended or revoked (or the key has no owning Application). Under the Applications model (ADR-0008) every key belongs to an Application, and a suspended or revoked Application disables all of its keys.

Fix: Ask an admin to re-activate the Application (Applications page → Activate), or mint a fresh key from an active Application via make mint-key.

ERR.AUTH.0010: cannot exchange a session key

Cause: You tried to call /v1/auth/session with a session token rather than a long-lived key. Session keys cannot themselves be exchanged.

Fix: Paste your long-lived key, not the session token from sessionStorage.

Session expired mid-action

Symptom: A request returns 401 after the console had been working fine; the console redirects you to /connect with the URL pre-filled.

Cause: The session token expired (default 8h TTL), OR the parent long-lived key was revoked elsewhere.

Fix: Paste your long-lived key again. The console returns you to the route you were on after re-exchange. If the long-lived key was revoked, the re-exchange will also fail; mint a new long-lived key.

"Insufficient permissions" everywhere

Cause: Your minted key's user has no roles assigned, so effective_scopes is essentially empty.

Fix: Either:

1. Use the bootstrap admin key (printed by make setup) to log in, then create roles and assign them via the UI.
2. Mint your key bound to a role: when calling make mint-key, pass ROLE=admin to assign the default admin role.

404 on an agent

Symptom: /agents/{name} renders "Not found", or the agent is missing from the Agents list.

Cause: Your effective scopes do not include agents:<name>:run. The API returns 404 (not 403) to avoid leaking the agent's existence.

Fix: Have an operator with roles:write assign you a role containing agents:<name>:run, or acaso_os:admin.

409 on delete

Symptom: Deleting a role, family, or genus returns 409 with a list of blockers.

Cause: The target has dependents. Roles cannot be deleted while assigned to users; families cannot be deleted while non-empty.

Fix:

• Role with users: the 409 response includes the affected user ids. Use the console's "Unassign all and retry" action, or unassign manually.
• Non-empty family / genus: clear children first. Force-delete (cascade) is out of scope for v1.

"Cannot delete: family has N genera, M specimens, K statements"

Same as 409 on delete, specific to graphium. See Workflows: Ingest and curate context for the deletion rules.

Console loads but the page is blank

Cause: A JavaScript error during render, often after upgrading the API behind the same connection.

Fix: Open DevTools Console. Look for a thrown error, copy the message and stack, and report it. Workaround: clear sessionStorage for the origin and reconnect.

Hot-reload not working in local dev

Cause: Wrong package manager (npm or yarn instead of pnpm), or stale .next cache.

Fix:

rm -rf packages/web/.next
make web-install
make web-dev

Use Node ≥ 20 and pnpm ≥ 9.

Still stuck

Capture the X-Request-Id from the failing response's headers and the audit log row (if any). Both correlate across logs and make support investigation tractable.