Help

FAQ & Troubleshooting

Stuck on install, sync, or wondering where your data lives? Jump to the question that matches your issue — each answer links back to the deeper reference page when one exists.

“KVault can’t be opened” on macOS

macOS Gatekeeper blocks unsigned apps on first launch. KVault is not yet notarized, so you’ll see this warning the first time you open it. See the Installation page’s Gatekeeper section for the full walkthrough.

The quick fix: right-click the KVault app in /Applications and choose Open from the context menu, then confirm. If that still fails, strip the quarantine attribute from Terminal: 

xattr -dr com.apple.quarantine /Applications/KVault.app

Windows SmartScreen blocks the installer

Windows Defender SmartScreen flags unsigned installers with a blue “Windows protected your PC” dialog. See the Installation page’s SmartScreen section for details.

To proceed, click More info on the dialog, then the Run anyway button that appears. The installer will then run normally.

App won’t start on Ubuntu 25.10+

Ubuntu 25.10 removed libwebkit2gtk-4.1-0 from its repositories, which is the WebKit runtime Tauri 2 currently depends on. Without it, KVault’s window will never open. See the Installation page’s Linux section for a full breakdown.

Until Tauri completes its GTK4 / WebKit migration, the options are:

  • Run KVault inside an Ubuntu 24.04 LTS VM or container that still ships the required WebKit package.
  • Stay on Ubuntu 24.04 LTS on the host until the upstream migration lands.
  • Wait for a future KVault release built against the newer Tauri WebKit stack.

Token validation fails

If KVault rejects your Cloudflare API token when adding an account, walk through this checklist:

  • The token must include the Account → Workers KV Storage → Edit permission. Read-only scopes are not enough — KVault needs Edit to write values and manage keys.
  • The token must not be expired. Cloudflare tokens can have an explicit TTL; check the token’s configuration in the Cloudflare dashboard.
  • The token’s Account Resources scope must include the account you’re trying to add. A token scoped to only one account can’t be used for another.

When in doubt, generate a fresh token from the Cloudflare dashboard with the correct permissions and try again.

Namespace sync seems stuck

If a namespace’s key list never finishes loading or appears frozen mid-sync, try these in order:

  • Force a re-sync with Cmd+Shift+R, or right-click the namespace in the sidebar and choose Re-sync.
  • Check your network connectivity — KVault needs to reach api.cloudflare.com to paginate through keys.
  • Verify the account’s token still has access to the namespace’s parent account (see token validation above).

Where are my API tokens stored?

Cloudflare API tokens live only in your operating system’s secure credential store — macOS Keychain, Windows Credential Manager, or the Linux Secret Service (GNOME Keyring / KWallet). They are never written to KVault’s SQLite database or to disk in plaintext. The accounts row keeps only the account metadata; the token is retrieved by account id at call time.

When you delete an account inside KVault, the associated keychain entry is removed in the same step.

Where is local data stored?

KVault writes its SQLite cache and workspace state to your OS’s standard app-data directory:

  • macOS: ~/Library/Application Support/com.kvault.app/
  • Windows: %APPDATA%\com.kvault.app\
  • Linux: ~/.local/share/com.kvault.app/

This directory contains the SQLite key-name cache and your saved workspace layout — no KV values and no secrets. Deleting it resets the local cache; your Cloudflare data is untouched.

Are KV values cached locally?

No. Only key names are cached locally, which is what makes filtering and search feel instant even for large namespaces. Every time you open a key, its value is fetched fresh from the Cloudflare API — there is no value cache to go stale, and closing KVault leaves no value data behind.

Can I edit binary values?

Not in v1. When a value is non-text, KVault renders it in a read-only hex viewer so you can inspect bytes without risk of corrupting the value. Binary editing is on the roadmap.

Text and JSON values can be edited freely in the code editor with syntax highlighting, IntelliSense, multiple cursors, and find-in-file.

How do I report a bug or request a feature?

Open an issue at github.com/uditalias/kvault/issues. Please include:

  • Your operating system and version.
  • Your KVault version (visible in Settings).
  • Clear steps to reproduce, plus the expected vs. actual behavior.

Feature requests are welcome in the same tracker — label them accordingly and describe the workflow you’re trying to unblock.