Troubleshooting

Most problems show a message that says what went wrong. Find the message, or the symptom, below.

Installing and starting#

Windows says “Windows protected your PC”

The builds aren’t code-signed yet. Check the file’s checksum, then click More info and Run anyway. More about the warning.

Linux: “error loading libfuse.so.2”

Run the AppImage with --appimage-extract-and-run, or install the FUSE 2 library. Package names by distribution.

Linux: “Cannot open display”

The app needs a graphical desktop session: X11, or Wayland with XWayland. It won’t start from a plain terminal login or over SSH without a display.

Linux: the app starts, but a model never loads

The AI engine needs glibc 2.34 or newer. Check with ldd --version. Ubuntu 20.04 and other older systems are too old. See the Linux requirements.

Opening a vault#

“Did not unlock.”

The passphrase or security key wasn’t accepted. The message is deliberately the same whatever the reason, so it never tells someone else how close they came. Check that:

• you picked the right vault file, and not a backup made before you changed the passphrase (backups keep their old passphrase);
• Caps Lock is off and the keyboard layout is the one you created the passphrase with;
• the security key is plugged in, and you touched it while the app showed “Touch your security key…”;
• for a vault that needs its passphrase and its key, you supplied both. The unlock screen says which the vault needs.

If you have truly forgotten the passphrase and have no backup factor, the vault can’t be opened. There is no recovery.

“The vault file isn’t there any more. It may have been moved or renamed, or the drive holding it removed.”

Nothing is wrong with your passphrase: the file wasn’t found, so no factor was tried. Reconnect the drive if it was removable, or click Choose vault file… and pick the vault where it is now.

“This vault is on a disk or in a folder that cannot be written to…” or “This vault file is read-only…”

The app won’t open a vault it couldn’t save to, so nothing you write is silently lost. This is common with a CD, a write-protected USB drive, or a file copied from a read-only location. Copy the vault somewhere you can write to, or clear the file’s read-only setting, and open it again.

“The vault file could not be read. Another program may have it open, or the disk may be failing.”

Close anything else that might be using the file: a second copy of the app, a sync client that is still uploading it, or a backup or antivirus program scanning it. Then try again. If it keeps happening on the same drive, copy the vault and your backups to another drive soon.

“This vault was written by an earlier version and has to be upgraded before it can be opened, but the file could not be written to.”

A new version upgrades older vaults the first time it opens them, and that needs write access. Copy the vault somewhere writable, keep a copy of the original, and open it from there.

“This vault says it was written in format v…, but … of the records … could not be read that way.”

The upgrade found records it couldn’t convert and stopped without changing the file, so nothing has been lost. Keep that file safe and don’t try to force it. Open a recent backup if you have one.

A screen titled “Some memories need a home” appears after unlocking

That isn’t an error. Vaults from earlier versions can hold memories that belong to no conversation, and the app asks where each one should go. What the choices mean.

Security keys#

The security key options aren’t offered

On Windows, security keys need a version of Windows with a recent WebAuthn API; if yours is too old, the create screen says “Update Windows to use this feature.” On Linux, install libfido2 (version 1.5 or newer): the app says “The security-key library (libfido2) is not installed.” when it’s missing. Security keys on Linux.

Linux: “Could not open the security key (… permission denied)”

Your account isn’t allowed to talk to the key. Add the udev rule and group described in Security keys on Linux, then unplug and replug the key.

“More than one security key is plugged in.”

When enrolling, leave only the key you want to enroll connected, so the vault isn’t bound to the wrong one. Enroll the backup key as a separate step.

“This security key has no PIN set.”

The app requires a PIN on the key, because the PIN is what proves the key is yours and not merely nearby. Set one with your key maker’s tool (on Linux, fido2-token -S), then try again.

“That PIN was wrong.”

Take care: keys allow only a few attempts. When the count shown reaches its end, the key locks itself.

“This security key has locked itself after too many wrong PINs.”

Unplug it and plug it back in to try again. If it stays locked, the only fix is resetting the key, and a reset erases the credential the vault depends on. Before you reset, open the vault with its backup key or backup passphrase if it has one.

“This security key did not return a derived secret” or “This is a U2F-only security key.”

The key doesn’t support the FIDO2 hmac-secret extension, which the app needs. Most FIDO2 keys have it; older U2F-only keys don’t. Use a different key.

“This security key is full and cannot store another credential.”

Remove credentials you no longer need with your key maker’s tool, or use another key.

Models#

“No .gguf chat models in that folder.”

The folder has no .gguf files, or only embedding models, which power memory search rather than chat. Choose the folder your chat model is in. Ollama’s model store doesn’t work, because its files don’t end in .gguf. Pointing the app at your models.

“Can’t find model on this machine”

The vault remembers a model that isn’t where it was, usually because the vault moved to another computer. Click Locate model… under the message and show the app the folder it’s in now. Taking a vault to another computer.

“Could not load that model: …” or “Model failed to load (see Settings)”

The text after the colon comes from the AI engine. The usual causes are:

• Not enough memory. Try a smaller model or a smaller quantization, close other large programs, or lower the context size.
• An incomplete or damaged download. Compare the file size with the one on the download page, and download it again.
• A file that isn’t a chat model, or uses an architecture this version of the engine doesn’t know yet.

The send button does nothing

No model is loaded yet. Look at the model line in the sidebar: “Loading model…” means wait a moment, while “No model loaded” or “Model failed to load” means choose one in Settings → Model.

Slow replies and the graphics card#

Replies are very slow

Check the sidebar’s model line. CPU means nothing is running on the graphics card; GPU (n layers) means part or all of it is. In Settings → Model, a note such as “Partial GPU: ~20 of 36 layers fit; the rest run on CPU” means the model is too big to fit on the card. A smaller quantization or model will be much faster.

“No GPU detected — running on CPU.”

The app found no graphics card it can use through Vulkan. Install or update the graphics driver from your card’s maker. On Linux, also install the Vulkan loader and your card’s Vulkan driver (package names). AMD and Intel cards are expected to work the same way as NVIDIA, but haven’t been tested yet. More about graphics cards.

A reply ends with “[generation error: the prompt … fills the …-token context, leaving no room to reply …]”

Your message plus what the app gathered for the AI didn’t leave room for an answer. Shorten the message, or raise the conversation’s context size in its settings and reload the model. A similar message says “the reasoning filled the … context”: the model thought for so long it ran out of room. The same fix applies.

The vault locked by itself#

“Locked after a spell of inactivity.”

Auto-lock did its job. Change how long it waits in Settings → Security. It doesn’t trigger while a backup or integrity check is running.

“The vault’s drive is no longer available, so the vault was locked.”

The drive holding the vault disappeared, for example a USB drive that was pulled out or a network drive that dropped. Reconnect it and open the vault again.

“Something went wrong, so the vault was locked to keep it safe. Please try again.”

The app hit an unexpected error. It locked the vault rather than carry on in an unknown state. Open the vault again; see crashes below if it keeps happening.

Memory#

The AI forgot something I told it

Memory brings back what looks relevant, and it can miss things. If a fact should always be in mind, pin it. If it remembered something wrong, correct it. How memory works explains what it can and can’t do.

“Semantic memory limited (model is on GPU)”

Searching memory by meaning needs an embedding model. Add a small embedding .gguf to your models folder; until then, the app matches keywords instead. Adding an embedding model.

“Wrong passphrase for this archive.”

A memory export has its own passphrase, chosen when it was exported and separate from the vault’s. Importing memories.

Backups and damage#

“Not backed up: …”

The text after the colon says why. The usual causes are a destination that is full, disconnected or read-only. If the copy didn’t read back correctly, it is discarded rather than left looking like a good backup. Choose another location and try again.

“… entries have been damaged and cannot be recovered from this file.”

An integrity check or backup found entries whose contents no longer match what was written. That usually means a failing drive. Stop writing to that drive, restore from your most recent backup, and check the backup too.

“The vault’s header is damaged; it is currently opening from its spare copy.”

The vault keeps a spare copy of its header and is using it. Your diary still opens, but the drive may be failing. Make a backup to a different drive now.

Crashes#

When the app hits an unexpected error it writes a short entry to a file named crash.log:

If the portable folder can’t be written to, the log goes to the installer location instead (on Linux, ~/.local/share/MyThoughtSafe). The log records the kind of error and where in the program it happened. File paths and your account name are removed, and it never contains anything from your diary, so you can read it yourself before sharing it with anyone.

Some crashes happen inside the system libraries the app uses and close the app without writing a log. On Windows, those appear in Event Viewer under Windows Logs → Application.

Next step#

Work faster with keyboard shortcuts.