Troubleshooting
Installing and starting
macOS: "DeepState can't be opened because Apple cannot check it…" - right-click the app → Open, or allow it in System Settings → Privacy & Security. Once.
Windows SmartScreen warning. More info → Run anyway. New releases trigger this until they build reputation.
Linux AppImage does nothing. chmod +x the file. If it still fails, run it from a terminal and
read the output; missing FUSE is the usual cause (sudo apt install libfuse2 on Debian/Ubuntu).
Linux: API keys disappear after restart. No keyring is available, so secrets were stored in plain text and something cleaned them up, or the app couldn't write them. Install GNOME Keyring or KWallet and make sure it is unlocked at login.
The app opens but the window is blank. GPU trouble. Launch from a terminal with
--disable-gpu to confirm; if that fixes it, update your graphics drivers.
License
"Invalid license key." Copy-paste the key from the email rather than typing it. Keys are case-insensitive but every character matters. Seat keys need the email as well.
"Maximum activations reached." The key is active on another computer. Deactivate there (Settings → License → Transfer License), or if that machine is gone, email support with the key.
"License validation required" after a few days offline. The app tolerates three days without reaching the license server. Connect once; it re-validates and carries on.
Pro features missing after upgrading. The app picks up tier changes at the next daily validation. Force it: Settings → License → Refresh, or restart the app.
The assistant
"Agent not configured." No provider is signed in. Settings → AI Provider: select DeepState AI (needs only the license) or add a key / sign in.
It answers but never creates nodes. You are in Plan mode - switch to Investigate. Or the model doesn't support tool calling (common with small Ollama models). Or Smart tool loading is on and the model hasn't requested the group it needs; ask it directly ("use the entity tools").
It creates duplicates. Ask it to "search the board first" or "merge X into Y". Boards with many similarly-named nodes make this worse; give things distinct titles.
"Budget exhausted" on DeepState AI. Your monthly allowance is used. Wait for the reset (date in Settings → License) or switch to your own provider key.
Responses stop mid-way / "context too long". Compact the conversation (compress icon in the panel header) or start a new chat. Reduce how many nodes you select before asking.
Autoresearch button is disabled. It only works in a brand-new chat. Click New chat first.
Claude OAuth: "Invalid authorization code". Copy the entire code shown after approving,
including everything after the # if present, and paste it within a minute or two.
ChatGPT login opens the browser but nothing happens. The callback uses a local port; a firewall or another app on that port blocks it. Use an API key instead.
Scraping and enrichment
Article stays on "scrape failed". The site blocks headless browsers or needs a login. Try
Re-scrape article; if it fails again, ask the assistant for wayback_fetch on the URL, or paste
the text into a Note.
Link preview is empty. The site publishes no OpenGraph metadata. The URL still works as a reference; add a title yourself.
Social post won't fetch. X: some posts are age-gated or from protected accounts and need a connected account. Reddit: rate-limited - wait a minute. Bluesky: the post is from an account that blocks logged-out viewing.
"Authentication expired" for X. Re-import cookies or log in again under Settings → Integrations.
Wikipedia enrichment attached the wrong person. Edit the actor and correct the Wikipedia fields; enrichment is a first guess by name.
Feeds
Feed never updates. Check Enabled on the node, and the interval. On a shared board only the device that created the feed polls it - if that device is off, nothing arrives until it's back.
Too many or too few articles. Adjust keyword filters and the relevance threshold; see RSS feeds.
YouTube quick-add fails. Use the exact @handle from the channel URL, not the display name.
Collaboration
Same network: peers never appear. Same Wi-Fi, no VPN, multicast allowed, firewall permits the app. On corporate networks use the relay.
Relay stuck on Connecting. URL must start with https://; outbound WebSockets must be
allowed. Check https://relay.getdeepstate.app/health in a browser.
Connected but nothing syncs. Both sides must hold the same key (same invite code generation) and use the same transport/URL. Ask the other side to Push full history.
"Changes waiting" never clears. An earlier change never arrived. Have a peer push full history, or apply the older changes file first.
Clock warning about a device. That device's clock is off by more than five minutes. Enable automatic time on it.
Files and data
Export/backup dialog flashes and nothing happens (Linux). An Electron/GTK bug with save dialogs. Update to the latest version - the app now asks for a folder and names the file itself.
Import says "Board limit reached". Personal licenses hold five boards. Archive one, or upgrade.
Media missing after moving to a new machine. You copied deepstate.db but not boards/.
Copy the whole data folder, or use a backup file which includes both.
Restore didn't apply. It applies on the next launch. Quit fully (not just close the window) and relaunch. If it still shows as pending, check disk space.
I archived a board by mistake. There is no un-archive in the app yet. Restore a backup from before, or email support with the board name - the data is still in your database.
Getting help
Email support@getdeepstate.app with your app version (bottom of the board select screen), platform, and what you did. If the app is misbehaving, launching it from a terminal and including the last lines of output speeds things up considerably.