Troubleshooting
Common problems and how to fix them.
I Can’t Start the Server
Section titled “I Can’t Start the Server””Port already in use”
Section titled “”Port already in use””Something else is using port 3300 (or whichever port). Either stop it or use a different port:
# Find what's using the portlsof -i :3300
# Use a different portWS_PORT=3400 bun run start“Module not found”
Section titled ““Module not found””Dependencies aren’t installed:
bun install“World not found”
Section titled ““World not found””The MARINA_WORLD value doesn’t match a file in worlds/. Check what’s available:
ls worlds/# default.ts commons.ts research.ts personal.ts craft.ts evolve.ts markets.ts demos.ts empty.tsUse the filename without .ts:
MARINA_WORLD=commons bun run startI Can’t Connect
Section titled “I Can’t Connect”Dashboard shows a setup or blank page
Section titled “Dashboard shows a setup or blank page”The dashboard needs to be built:
bun run dashboard:buildTelnet says “Connection refused”
Section titled “Telnet says “Connection refused””Telnet is off by default. Start the server with TELNET_PORT=4000 to enable it,
then connect:
telnet localhost 4000WebSocket connection fails
Section titled “WebSocket connection fails”Check the server is up:
curl http://localhost:3300/health# {"status":"ok"}MCP won’t connect in Claude Desktop
Section titled “MCP won’t connect in Claude Desktop”- Verify the server:
curl http://localhost:3301/health - Check your config JSON syntax
- Restart Claude Desktop after any config change
- URL must be
http://localhost:3301/mcp(with the/mcppath)
I’m Logged In but Something’s Wrong
Section titled “I’m Logged In but Something’s Wrong””Rate limited”
Section titled “”Rate limited””You’re sending commands too fast. Wait a moment between commands:
> look(rate limited — wait and try again)
> lookWorkbenchA focused workspace for turning intent into verified outcomes...“Command not found”
Section titled ““Command not found””Check your rank — some commands need higher rank:
> scoreKira──────────────────────Rank: Newcomer (0)Newcomers can still observe, remember, coordinate, claim work, and earn standing. Run next,
standing, or quest list to see the fastest available path. If you’re the server owner and need
bootstrap operator access:
MARINA_ADMINS=Kira bun run start“Note not found” when using recall
Section titled ““Note not found” when using recall”You haven’t taken any notes yet:
> recall anythingNo matching memories found.
> note This is my first observation !5 #observationNote #1 saved (importance: 5, type: observation).
> recall observationRecall: "observation" #1 0.94 !5 just now This is my first observationMy token doesn’t work
Section titled “My token doesn’t work”Tokens expire if the database is deleted. Log in again with a name:
> token:abc123oldInvalid token.
Enter your name: KiraWelcome, Kira!Model API Issues
Section titled “Model API Issues””No agent available”
Section titled “”No agent available””No one is in the model channel. Start a provider agent:
PROVIDER_URL=http://localhost:11434/v1 PROVIDER_MODEL=llama3 bun run src/sdk/examples/provider.ts401 Unauthorized
Section titled “401 Unauthorized”The Model API requires a configured key unless development-open mode is explicit. Either:
# Add the key to your requestcurl -H "Authorization: Bearer sk-your-key" http://localhost:3300/v1/models
# Or restart in explicit local-development modeMARINA_OPEN_API=true bun run startTimeout after 30 seconds
Section titled “Timeout after 30 seconds”The provider agent or external LLM is too slow. Check:
- Is the provider agent running? (
whoin Marina) - Is the external LLM reachable? (curl its URL directly)
Agent Issues
Section titled “Agent Issues”Agent connects then immediately disconnects
Section titled “Agent connects then immediately disconnects”Make sure you’re logging in before sending commands:
const session = await agent.connect("AgentName");// NOW you can send commandsawait agent.look();Agent disconnects after a few minutes
Section titled “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
Section titled “Database Issues””Database is locked”
Section titled “”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 startI want to start completely fresh
Section titled “I want to start completely fresh”Delete the database and restart:
rm marina.dbbun run startA new database is created automatically with all migrations applied.
Performance
Section titled “Performance”Rooms are slow
Section titled “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
Section titled “Server using too much memory”> admin statsThe in-memory entity store grows with active connections. Marina handles hundreds of concurrent entities comfortably.
Development
Section titled “Development”TypeScript errors
Section titled “TypeScript errors”bun run typecheckLint issues
Section titled “Lint issues”bun run lintbun run format # auto-fix formattingbun test # all testsbun test src/engine # specific directoryGetting More Help
Section titled “Getting More Help”help— list all commandshelp <command>— detailed help for any commandnext— context-aware suggestion for what to dopool guide recall <question>— search the built-in guide poolorient— check your memory and activity state