Troubleshooting - Inktomi93/OrbWeaver GitHub Wiki

Find the symptom, try the fix. If yours isn't here, check Known issues, which lists the rough edges that are already known, and then Report a bug.

Windows Defender blocks pnpm. Install pnpm with winget instead, then carry on with the rest of Install:

winget install -e --id pnpm.pnpm

The start fails because the port is already in use. Something else is using port 8788. It may be an earlier Orbweaver you forgot about: a terminal still running it, or the Docker container, which starts itself again after a reboot until you stop it.

• From source: run pnpm start --port 9000 to use another port for one run. To keep a different port, run pnpm start --setup and answer the port question.
• Docker: put ORB_PORT=9000 in .env next to docker-compose.yaml, then run docker compose -f docker-compose.yaml -f docker/compose.build.yaml up -d.

Open the new port in your browser. On Windows, start.cmd keeps its window open when the start fails, so you can read why.

The first start feels stuck, or the download is slow. On the first start Orbweaver downloads its built-in search model, about 1 GB, in the background. The app opens straight away and works while it downloads, but search waits for it. It only downloads once.

• On a slow or metered connection, set LOCAL_LIGHT_PREFETCH=off in your settings file. Nothing downloads until a feature first needs it, so the wait moves to that moment instead of going away. The settings file is .env for a source install, and docker/orbweaver.local.env for Docker.
• If the download fails, for example because you went offline, Orbweaver logs a warning, keeps running, and tries again the next time something needs the model.
• If you already point search at a model server of your own, nothing is downloaded for it.

Your phone or another computer can't open it. A fresh install answers on the computer it runs on and nowhere else. To let other devices in, the install needs a sign-in: from source, run pnpm start --setup and choose me and friends. Share with friends has the steps.

You're using WSL2 and other devices still can't reach it. Besides the sign-in above, turn on mirrored networking in WSL: set networkingMode=mirrored in your .wslconfig (Windows 11).

A friend's link stopped working. The link from Start sharing changes every time sharing starts. Send them the new one. → Share with friends

Sign-in fails behind a reverse proxy or tunnel. Check these in order:

• Everything answers "401" (unauthorized). A "just me" install never signs in a request that came through a proxy or tunnel. Switch the install to a sign-in first, then put the proxy in front. In Docker that takes three settings: AUTH_MODE=local, AUTH_FALLBACK=deny and an empty AUTH_FALLBACK_TRUSTED_PEERS=.
• "This address is not allowed." The name you typed in the browser isn't one Orbweaver knows. Add it to ALLOWED_HOSTS and restart. The error page names the host to add. If your proxy rewrites the Host header to its own upstream name, make it pass the browser's through instead. An IP address and localhost need no entry.
• The sign-in page warns about plain http on an https address. The proxy isn't sending X-Forwarded-Proto: https. It should also pass X-Forwarded-Host and X-Forwarded-For.
• Live updates stall or arrive late. Turn off response buffering for Orbweaver in the proxy.

A local model server (Ollama, LM Studio, KoboldCpp and so on) can't be reached.

1. Open the connection's Diagnostics and press Check again under Reachability. "Reached it." means the server answered. "Can't reach <host>" means nothing answered. "answered HTTP 404" (or another status) means the server is running but refused the request, which usually means a wrong path in the URL. Send a test request, in the block above, shows the address Orbweaver called and what the server answered.
2. If the Server URL field says the address "is a private address this deployment does not admit", or that a name like host.docker.internal "resolves to" one, press Admit under it. The button shows the host and port, and only the owner sees it. Admit adds that one port, so another port on the same host needs its own entry.
3. If Orbweaver runs in Docker, 127.0.0.1 and localhost mean the container. Use host.docker.internal instead, like http://host.docker.internal:11434, and admit that name too. On Linux, a server that listens only on loopback (Ollama's default) also has to be set to listen on all interfaces.
4. Check the server is running and the URL starts with http://. You can leave /v1 off, because Orbweaver adds it. A URL that already ends in a longer path, such as /v1/chat/completions, is the one that breaks.

A local model forgets the start of the chat too soon. Orbweaver assumes an 8,192-token context window for a model on your own server that doesn't report one, and the context window row says (assumed). Open the connection, expand Advanced, and press Override on context window under What this server accepts.

The game panel says Read-only. Orbweaver doesn't know your Chat model can make tool calls. For a model on your own server that can, declare them: open the connection, expand Advanced, find the tool calls row under What this server accepts (it reads not stated), press Override and pick yes, one at a time or yes, several at once.

→ Connect a model

Memory needs three things.

1. The switch. Remember earlier in long chats is under Chat behavior in Settings. It's off on a fresh install, and turning it on asks first. In a room you host, your switch is the one that counts. For chats you already have, tick Also build memory for all my existing chats now when you turn it on, or run Memory backfill from Jobs later.
2. A Utility model. Your first connection asks for one in Set up your first model. If you chose Not now, set one under Settings, Connections, Model roles. Without one, memory summaries stay paused, and the Memory section says so beside an Open Model roles button. They run on the host's Utility model.
3. Allow background work on the connection the Utility model uses. A connection without it is greyed out in the Utility model menu, and the role offers the switch right there.

Also:

• A short chat has nothing to recall. The most recent messages are sent as they are, and memory only brings back older ones.
• The brain icon on a chat shows what memory did on the latest turn, and stays muted when nothing was recalled. As host, you can open it to see which memories would be considered and how well each matches, worked out with your current settings.
• In a group chat, a character only keeps a memory of their own when Per-speaker is on and so is Each character sees only their own card, under Advanced in the group settings. It follows when each character was seated in the room, whatever they witnessed in the story.

→ How memory works

Corpus fills in from background work, in this order.

1. The built-in search model has to finish downloading. See the first-start fix above. Until it does, nothing can be indexed.
2. Your library has to be indexed. Open Jobs and look for Index (embeddings). If nothing is running, use Run a job... to start it. Background corpus indexing under Admin, Operations keeps the index current once it's built, and it's on unless someone turned it off. Indexing and search run on the built-in model on your computer. If you moved Text embedding to your own server under Model roles, that connection has to be reachable, and changing it re-indexes everything.
3. Dossiers, archetypes and the genre colors need the understanding pass. Press Run the understanding pass on Explore in Corpus. It runs on your Utility model, so the button stays greyed out, with an Open Model roles button beside it, until one runs. It shows how many model calls it will make and asks before it starts. The map itself only needs at least three of your characters indexed.
4. Scenes and Memories search come from memory. They only find chats with memory built, so they need Memory on, and Memory backfill (or the offer when you turn Memory on) to include older chats. They cover chats you host.

Some of the empty screens send you to the Refinery. That's the wrong place, and it's listed in Known issues.

Read the message on screen first, or the log in the window Orbweaver runs in. A start that is refused over a setting names the setting and what it needs. If that doesn't do it, Report a bug says what to include.