Troubleshooting

Troubleshooting

Common problems and how to fix them. Most decryption issues come down to the passphrase or an access rule that is intentionally blocking you.

"My file won't decrypt" — quick diagnosis

flowchart TD
  A["Decryption fails"] --> B{"Error: wrong passphrase?"}
  B -->|"yes"| C["Check exact passphrase<br/>(case-sensitive, spaces)"]
  C --> C2{"Was it a dual-key file?"}
  C2 -->|"yes"| C3["Provide BOTH passphrases"]
  C2 -->|"no"| C4{"Secret question set?"}
  C4 -->|"yes"| C5["Provide the exact answer"]
  B -->|"no, it says expired"| D["The TTL passed — it cannot be opened anymore"]
  B -->|"no, it says locked"| E["Max attempts reached<br/>(tracked locally)"]
  B -->|"no, IP not allowed"| F["Open it from an allowed IP / network"]

Loading

Decryption problems

Symptom	Cause	Fix
"Wrong passphrase"	Typo, wrong case, or extra space	Re-enter carefully. Passphrases are case-sensitive. If it was generated, copy-paste it.
Fails even with the right passphrase	It is a dual-key file	Provide both passphrases (dual passphrase).
Asks for an answer	A secret question was set	Enter the exact answer used at encryption (secret question).
"Expired"	The TTL deadline passed	The file is intentionally unopenable now; ask the sender to re-share (TTL / expiration).
"Locked" / too many attempts	Max attempts reached	The counter is local (localStorage in the browser, ~/.zefer/attempts.json in the CLI).
"IP not allowed"	An IP allowlist is set	Open it from an allowed address/network.
Tampering / integrity error	The file was modified or truncated	Re-download the original .zefer; the authentication tag detected a change.
Forgot the passphrase	By design, secrets are not recoverable	There is no backdoor or reset — the data cannot be recovered. Use a password manager next time.

App / browser issues

Symptom	Fix
Encryption seems unavailable / errors	The Web Crypto API requires a secure context — use https:// (or localhost) and a modern browser.
Large file fails or the tab runs out of memory	Limits are device-aware (RAM/CPU); see /device. For very large files prefer the CLI, which streams in chunks.
Installed PWA looks stale after an update	Pages are network-first when online; reload, or clear the site's cache/service worker.
Nothing downloads	Check the browser's pop-up/download blocker; the file is generated locally and triggered as a download.

CLI issues

Symptom	Fix
command not found: zefer	Install globally (npm install -g zefer-cli) and ensure npm's global bin is on your PATH, or run npx zefer-cli <command>.
Node.js errors on an old runtime	The CLI targets Node.js 20+. Upgrade Node, or use a standalone binary (no Node required).
Want no Node.js at all	Download the standalone binary for your platform (see CLI).
Verifying a download	Each release ships checksums.txt; verify the SHA-256.

MCP issues

Symptom	Fix
The agent doesn't see Zefer's tools	Confirm the mcpServers config (global zefer mcp or npx -y zefer-cli mcp) and restart the client.
It launches the CLI instead of the server	Use zefer mcp explicitly; auto-detection only triggers with no args and piped stdin. See MCP Server.

Still stuck?

• Inspect the file (no passphrase needed) with the .zefer File Analyzer or zefer info to confirm its format and KDF level.
• For a suspected security issue, follow the Security Policy — don't open a public issue.
• Otherwise, open an issue on the repository.

---

📖 Glossary — terms on this page: dual passphrase · secret question · TTL / expiration · authentication tag · Web Crypto API · chunk. Full list in the Glossary.