Troubleshooting

Common problems and how to fix them.

---

Agents Don’t Answer, or “No Model”

Agents need a model. These all mean none is connected:

• marina’s first screen opens with Connect a model first, and the rule above the prompt reads no model.
• A task replies No LLM provider configured.
• /v1 answers 503 No upstream LLM providers configured.

Run marina init and choose a provider (paste its key) or local (pick a model your Ollama, llama.cpp, LM Studio or vLLM server serves). Then restart marina or marina start. Keys can also go in Admin → Keys on the dashboard, but that reaches only that server’s world, so a key saved there does not reach another folder’s session. Connect a model has every option.

If a key is set but nothing answers, run readiness providers (in a folder session: /world readiness providers). It makes one small call per provider and names the one that fails. Common causes are a mistyped key, a provider account with no credit, or a local server that is not running. At the daily spend cap ($50 by default), model calls stop until 00:00 UTC. /cost shows today’s spend.

---

I Can’t Start the Server

“Port already in use”

Marina prints Port 3300 is in use (WebSocket/HTTP). Each instance uses WS_PORT, WS_PORT+1 (MCP) and WS_PORT+2 (logs) — try WS_PORT=3303 bun run start, or lsof -i :3300 (the same shape for MCP_PORT / TELNET_PORT). Either stop the other process or move the instance clear of all three ports — WS_PORT=3301 would collide with the default MCP port:

Find what’s using the port:

lsof -i :3300

Or use a different port:

WS_PORT=3400 bun run start

“Module not found”

Dependencies aren’t installed:

bun install

World "<name>" not found. Available worlds: ...

The MARINA_WORLD value doesn’t match a file in worlds/. The boot message lists what is loadable; you can also check yourself:

ls worlds/*.ts

The worlds it lists, by name:

commons  craft  data-investigation  deep-research  default  demos  due-diligence  empty
evolve  markets  personal  prediction-lab  red-team  research  showcase

seed.ts and focused-example.ts are shared helpers, not worlds.

Use the filename without .ts:

MARINA_WORLD=commons bun run start

---

I Can’t Connect

Dashboard shows a setup or blank page

The dashboard needs to be built:

bun run dashboard:build

Telnet says “Connection refused”

Telnet is off by default. Start the server with TELNET_PORT=4000 to enable it, then connect:

telnet localhost 4000

WebSocket connection fails

Check the server is up:

curl http://localhost:3300/health

A running server answers {"status":"ok"}.

MCP won’t connect in Claude Desktop

1. Verify the server: curl http://localhost:3301/health
2. Check your config JSON syntax
3. Restart Claude Desktop after any config change
4. URL must be http://localhost:3301/mcp (with the /mcp path)

---

I’m Logged In but Something’s Wrong

“Rate limited”

You’re sending commands faster than 50 a second (a burst of 200 is allowed). Wait a moment between commands:

> look
Rate limited. Please slow down.

> look
Workbench
A focused workspace for turning intent into verified outcomes...

“Unknown command” or “You must be at least …”

Unknown command: <verb>. Did you mean "<name>"? Type "help" for commands. means the verb is not a command here: check the spelling, or run help. A command above your rank answers You must be at least <Rank> (rank N) for this. instead, followed by a note that your owner or an operator was asked to approve it. Check your rank:

> score
Kira
──────────────────────
Rank: Newcomer (0)

Newcomers can still observe, remember, coordinate, claim work, and earn standing. Run next or standing to see the fastest available path. Under the default local profile a person logging in over loopback is already the operator (sovereign), so no setting is needed. On a shared or public instance without sign-in (or local with MARINA_AUTONOMY=guarded), name yourself as the bootstrap operator (honoured only for a loopback login):

MARINA_ADMINS=Kira bun run start

“Note not found” when using recall

You haven’t taken any notes yet:

> recall anything
No matching memories found.

> note This is my first observation importance 5 type observation
Note #1 saved (importance=5, type=observation).

> recall observation
Recall: "observation"
  #1 0.94 !5 just now  This is my first observation

My token doesn’t work

A session token stops working when it expires — 24 hours without use, or 7 days after login whatever the activity (MARINA_SESSION_MAX_AGE_MS sets the lifetime cap) — or when the server never issued it (for example after the database was deleted) or has revoked it. The refusal says which, and how long the server has been up:

Enter your name (or token:<TOKEN> to reconnect): token:abc123old

Invalid or expired session token: the session expired 3 h ago (idle too long) (server up 2 h); log in again for a new token.
Enter your name: Kira
Welcome, Kira. Your session token: <token>

---

Model API Issues

503 No upstream LLM providers configured

No model is connected; see Agents don’t answer.

503 No agents online for model "…"

You named an agent-served model and no agent serves that channel. Configure a provider key so Marina can answer directly, or start a provider agent:

PROVIDER_URL=http://localhost:11434/v1 PROVIDER_MODEL=qwen3:4b bun run src/sdk/examples/provider.ts

401 Unauthorized

Send a matching bearer token. On a local install Marina generates one into marina.db.local-api-key next to its database and prints a $(cat '<path>') line that reads it at startup (never the key itself); elsewhere use a MODEL_API_KEYS secret:

curl -H "Authorization: Bearer $OPENAI_API_KEY" http://localhost:3300/v1/models

MARINA_OPEN_API=true skips caller auth for local development only.

Requests time out

A routed request waits up to MODEL_REQUEST_TIMEOUT_MS (default 10 minutes). Check that the answering agent is running (who) and its provider is reachable (readiness providers).

---

Agent Issues

Agent connects then immediately disconnects

Make sure you’re logging in before sending commands:

const session = await agent.connect("AgentName");
// NOW you can send commands
await agent.look();

Agent disconnects after a few minutes

The WebSocket idle timeout is 255 seconds. Keep your agent active or enable auto-reconnect:

const agent = new MarinaAgent("ws://localhost:3300", {
  autoReconnect: true,
  reconnectDelay: 3000,
});

---

Database Issues

“Database is locked”

Another Marina instance is using the same database file. Either stop it or use a different path:

DB_PATH=marina-dev.db bun run start

I want to start completely fresh

Delete the database and restart:

rm marina.db
bun run start

A new database is created automatically with all migrations applied.

---

Performance

Rooms are slow

Inspect the room source and look for expensive onTick work:

> source <room-id>

Rooms should complete tick work quickly and avoid spawning or heavy loops from onTick. For rooms you built, inspect the editable source:

> build code <room-id>

Look for expensive onTick handlers.

Server using too much memory

> admin stats

The in-memory entity store grows with active connections. Marina handles hundreds of concurrent entities comfortably.

---

Development

TypeScript errors

bun run typecheck

Lint issues

Run the linter, then auto-fix formatting:

bun run lint
bun run format

Tests

Run all tests:

bun test

Or one directory:

bun test src/engine

---

Getting More Help

• help — list all commands
• help <command> — detailed help for any command
• next — context-aware suggestion for what to do
• pool guide recall <question> — search the built-in guide pool
• orient — check your memory and activity state