Troubleshooting

Most problems fall into one of a few buckets. Find your symptom below.

CLI setup

`aios: command not found`

The shell launcher, read-only onboarding inspection, and scaffolder ship in aios-workspace and do not require a package install. The interactive onboarding wizard uses the toolkit’s installed packages. If aios is not on your PATH, from inside the toolkit checkout run:

npm link                       # or: export PATH="$PWD/bin:$PATH"

Then aios status should work from any workspace.

`aios status` reports files as blocked

That’s the default-deny working as designed: a file with no tier frontmatter does not sync. Add an access: field to the file’s YAML frontmatter (team, client/company, or — to keep it local — private/admin).

Push errors

`401` on push

Invalid or missing API key. Check that:

AIOS_API_KEY is available from your environment or the workspace’s ignored .env. aios.yaml names the variable with api_key_env; never put the secret itself in YAML.
The key is the full aios_<key_id>_<secret> string shown once when you generated it from your Team Brain profile. If you lost it, revoke it and generate another.
aios whoami succeeds. It validates the key with GET /api/v1/me.

`422` on push

The item has admin tier — admin content is never accepted and never written to the database. Fix the access frontmatter of the file you’re pushing: change private/admin to team (or client/company for outward content), or leave it private and stop trying to push it.

`403` on push

Your key is not allowed to use that operation. The key is authoritative for team identity; team_id is only an optional compatibility hint and, when present, must match the key’s team. Some endpoints (codebase/metrics ingest) are team-tier only and reject external-tier keys with 403.

`429` on push

Rate limit — sync writes are capped (60 items/min per key). Wait a moment and retry, or push in smaller batches.

Identity & access

Your identity isn’t on the roster

People are invite-only; an admin must create your member row before you can sign into the dashboard. After signing in, generate your own per-member API key from your profile. If your email cannot log in, ask a Team Brain admin to invite you:

npm run admin -- create-member you@example.com --name "Your Name" --handle you --role member --team aios

See Onboarding a contributor for the full path.

Brain not reachable

If aios push, pull, or query can’t connect:

Check brain_url in aios.yaml (or AIOS_BRAIN_URL in the environment) points at the right host — your admin’s deployed URL, or http://localhost:3000 for a local brain.
Confirm the brain is actually running and reachable from your machine.

Local brain setup

If you’re running the Team Brain locally for development, the brain repo’s DEVELOPMENT.md has the full setup and a troubleshooting table. The most common ones:

Symptom	Fix
`relation "..." does not exist` / empty dashboard	Schema/seed not loaded → `npm run pg:schema && npm run dev:seed`
Auth / cookie errors	`AUTH_SECRET` unset in `.env.local`
Invite / magic links point at the wrong host	Set `APP_URL` to your absolute base URL
Live query errors, everything else works	No LLM configured — set `ANTHROPIC_API_KEY` or `LLM_BASE_URL` (see `docs/PROVIDERS.md`)
`ECONNREFUSED 127.0.0.1:5434` in data-mechanics tests	The test Postgres container is down → `npm run db:test:up`

Still stuck?

Open an issue on the relevant repo, or reach out to John at john@john-ellison.com.