When something goes wrong
For the person who set up Stuga.
Start with the symptom below. If a teammate sees Can’t reach the node or This node can’t reach its database, ask them to keep the tab open while you investigate.
Open Stuga on another device
Section titled “Open Stuga on another device”If Stuga opens on its own Mac but not another device:
- Check that both devices are on the same Wi-Fi or office Wi-Fi. Guest Wi-Fi can keep devices apart.
- On the Mac running Stuga, allow incoming connections if the firewall asks about node.
- Try the Mac’s IP address if the address ending in .local won’t open. Check that the address is still current.
See Open Stuga on other computers and phones.
If it opens on a phone but not your Mac’s browser, the browser may have lost its permission to find devices on your Wi-Fi:
- Open System Settings → Privacy & Security → Local Network and turn on the browser.
- Quit the browser with ⌘Q and reopen it. Choose Allow if it asks to find nearby devices.
- Restart the Mac if it still won’t open.
Restart Stuga on a Mac
Section titled “Restart Stuga on a Mac”If the menu says Stuga is not responding, choose Restart Stuga… and enter the password of a Mac account allowed to manage the computer. If it still fails, choose Show Logs and use the technical troubleshooting guide linked below.
If the menu says Stuga is older than its data, an earlier version was opened on data a later one used, and it changed nothing. Restarting won’t help: choose Open Stuga, and the page says what to do. To go back to an earlier version, see Restore on a Mac.
Get documents saving again
Section titled “Get documents saving again”A document or database shows on its page when its connection has trouble:
- Offline: this device has lost its connection. What you type stays on the page and is sent when it’s back.
- Reconnecting: Stuga isn’t answering. Check the Stuga menu, as in Restart Stuga on a Mac.
- The node can’t store changes: Stuga is running but can’t store them yet. Keep the page open; if it lasts, restart Stuga.
- Changes not sent yet: keep the page open until it clears. Leaving the page asks first.
If sign-in works but documents never connect, try the address from Copy Address in the Mac’s Stuga menu. Stuga may not recognize the web address you were using. For a custom address, follow Network access on GitHub.
Reconnect an AI tool
Section titled “Reconnect an AI tool”- A workspace is missing: sign in from the AI app again and select that workspace.
- It only reads: reconnect with Read and make changes. For an AI tool using a key, check the key’s access.
- It asks to sign in again: sign in again. Its connection may have been revoked or expired.
- Claude Desktop shows no tools: approve the sign-in waiting in your browser, or quit Claude fully and reopen it.
See Choose what an AI tool can reach.
Set up the decision model
Section titled “Set up the decision model”Set up the decision model shows in the library until it is set up: until then, nothing an AI saves is checked, and search results keep their plain order. Set it up under Decision model in Settings → This node → AI providers.
If Test under Edit fails, the page says why. A key the service didn’t accept is wrong, revoked or for another service: paste it again.
Improve search by meaning
Section titled “Improve search by meaning”In Settings → This node → AI providers, under Semantic search:
- Search shows unrelated documents: choose Edit, then Advanced, then Strict under Search strictness, and Save.
- Search misses documents that say the same thing in other words: choose Loose the same way.
- Couldn’t measure appears: the message says why. Stuga tries again by itself; Measure again tries now.
- The page says the AI can’t tell related text from unrelated: choose Edit and another AI.
See Set up the decision model and semantic search.
Help someone sign in
Section titled “Help someone sign in”Forgot password? on the sign-in page tells people to ask an administrator. For a forgotten password, create a reset link. For an invalid invite link, create another in Settings → This workspace → Members.
- Set up the decision model and semantic search — check the AI services.
- Back up and restore — return to saved data.
More detail: Troubleshooting on GitHub.