# Context pack: Desktop app Source: https://nordvec.com/docs/guides/desktop Pack: https://nordvec.com/docs/packs/desktop This pack bundles one Nordvec guide with the guides it builds on and the guides it links to, in reading order, so an assistant reading it meets no reference it cannot follow. ## Contents 1. [Desktop app](https://nordvec.com/docs/guides/desktop) (this guide) 2. [Install, data directory and logs](https://nordvec.com/docs/guides/desktop/install-and-data) (linked from this guide) 3. [Desktop app known issues](https://nordvec.com/docs/guides/desktop/known-issues) (linked from this guide) --- # Desktop app Source: https://nordvec.com/docs/guides/desktop Install the Nordvec desktop app, see what it writes to disk, and find out why it declines or skips a file. The desktop app syncs the folders you choose on your computer into Nordvec. These pages cover what it installs, where it keeps its data and log file, and what each message it shows means. - [Install, data directory and logs](https://nordvec.com/docs/guides/desktop/install-and-data): What the Nordvec desktop app installs on Windows, macOS and Linux, every file it writes to disk, and where its log file is. - [Desktop app known issues](https://nordvec.com/docs/guides/desktop/known-issues): Why the Nordvec desktop app declines a folder, skips a file, holds a removal or stops syncing, and what to do about each. --- # Install, data directory and logs Source: https://nordvec.com/docs/guides/desktop/install-and-data What the Nordvec desktop app installs on Windows, macOS and Linux, every file it writes to disk, and where its log file is. This page states where the desktop app writes on each operating system, for your own records or an IT review. It is generated from the app's build configuration and the file names its code writes, so it changes when they do. The app is **Nordvec Desktop**, application id `com.nordvec.desktop`. ## Windows [#windows] * **Installer:** an `.exe` setup program for x64. * **Install for:** the installer asks whether to install for you only or for everyone on the computer. You only is preselected and needs no administrator rights. * **Install folder:** you can choose it in the installer. * **Uninstalling** removes the data directory below with the app. Updating does not. * **Data directory:** `%APPDATA%\Nordvec Desktop` * **Log file:** `%APPDATA%\Nordvec Desktop\logs\nordvec-.log` ## macOS [#macos] * **Download:** a disk image (`.dmg`) or a `.zip` archive, for Apple silicon and Intel Macs (one universal build). * **Requires:** macOS 13.0 or later. * **Removing the app** leaves the data directory below in place; delete it to remove the local sync data. * **Data directory:** `~/Library/Application Support/Nordvec Desktop` * **Log file:** `~/Library/Application Support/Nordvec Desktop/logs/nordvec-.log` ## Linux [#linux] * **Download:** an AppImage for x64. It runs as your user, with no system-wide install. * **Removing the app** leaves the data directory below in place; delete it to remove the local sync data. * **Keyring:** the app needs a running gnome-keyring or KWallet to encrypt its local sync data, and does not sync without one. * **Data directory:** `~/.config/Nordvec Desktop` * **Log file:** `~/.config/Nordvec Desktop/logs/nordvec-.log` * When `XDG_CONFIG_HOME` is set, the data directory is `$XDG_CONFIG_HOME/Nordvec Desktop` instead. ## What is in the data directory [#what-is-in-the-data-directory] Everything the app keeps on your computer is in the data directory for your operating system, above. Each signed-in account has its own sync store. | Name | What it holds | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sync-state-.sqlite` | The sync store for one signed-in account: watched folders, exclusions, the upload and removal queues and what has synced. File names and paths in it are encrypted with a key the operating system's keychain protects. | | `logs/nordvec-.log` | The app's log for one day. It records events, counts and error codes, and every line names the app version that wrote it. It is written not to contain file names, paths or file contents. | | `logs/nordvec-.1.log` | The earlier part of a day's log, kept when that day's log reaches its size limit. At most one per day. | | `window-state.json` | The window's last size and position. | | `ui-locale` | The language of the last page the app showed, so the tray menu and notifications use it. | | `update-health.json` | When the app last checked for updates and whether the checks are failing. | | `whats-new-version` | The last version whose list of changes the app has shown, so each update's changes are shown once. | | `first-run-done` | Marks that the first launch has run, so start-at-login is turned on for a new install only. | | `crash-ledger.json` | When the app last stopped because of an error, as times only, so a second stop soon after reopening keeps it closed instead of reopening it again. | While the sync store is open, SQLite keeps `-wal`, `-shm`, `-journal` files beside `sync-state-.sqlite`; they belong to the store. The app also keeps the signed-in session's cookies and site storage in the data directory. The cookie store is encrypted with a key the operating system's keychain protects. On a computer that ran an early build, you may also find: | Name | What it holds | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sync-state.json` | State written by an early build. At sign-in the app hands it to the account that owns it, and keeps it when it cannot tell whose it is. | | `logs/nordvec.log` | The log an early build wrote. It is deleted with the daily logs once it is old enough. | | `logs/nordvec.log.old` | The previous log an early build kept beside it, deleted on the same terms. | | `sync-state-.json` | Per-account state written by an early build. At sign-in the app copies it into the sync store and renames it once the copy reads back. | | `sync-state-.json.imported` | The same early state after its contents were copied into the sync store. It holds file names and paths unencrypted and nothing reads it again, so it is safe to delete. | ## Log file [#log-file] The app writes one log file per day, `logs/nordvec-.log` in the data directory, where the date is the day on your computer. To open their folder from the app, choose **Help > Show Log File**. When a day's log reaches 5 MB, its earlier lines move to `nordvec-.1.log`, so one day keeps at most two files. The app keeps the last 14 days, today included, and at most 50 MB of logs in total, deleting the oldest days first. It never deletes today's log, and it deletes only files with these names. Every line names the build that wrote it, as `v= sha=` after the time and level. ## Which version you have [#which-version-you-have] * Windows: choose **Help > About Nordvec Desktop**. * macOS: choose **Nordvec Desktop > About Nordvec Desktop**. * Linux: choose **Help > About Nordvec Desktop**. * Every launch also writes a line starting `app_ready version=` to the log file, followed by the version. ## Reporting a problem [#reporting-a-problem] Check the [known issues](/docs/guides/desktop/known-issues) first. To report a bug, include the app version and, if you can, the log file. The app is written not to log file names, paths or file contents, but read the log before you share it and remove anything you do not want to send. --- # Desktop app known issues Source: https://nordvec.com/docs/guides/desktop/known-issues Why the Nordvec desktop app declines a folder, skips a file, holds a removal or stops syncing, and what to do about each. Each entry below is a decision the desktop app makes on purpose. This page is generated from the codes the app decides with, so every refusal code it can report is listed here with its cause and a workaround. If what you see is not here, [report it](/docs/guides/desktop/install-and-data#reporting-a-problem) with your app version and log file. ## Folders the app will not add [#folders-the-app-will-not-add] The app declines these folders when you pick them, and says why. ### A whole drive cannot be added [#a-whole-drive-cannot-be-added] What you see: **A whole drive is too broad to sync. Pick a folder on it instead.** **Cause:** The root of a drive holds far more than documents, and watching it would make every scan and removal walk the entire drive. **Workaround:** Add the folders on that drive that hold your documents, one at a time. ### Your home folder cannot be added [#your-home-folder-cannot-be-added] What you see: **Your account folder holds app data and settings as well as documents, and its name is your computer's account name. Pick Documents, Desktop, or another folder inside it.** **Cause:** Your home folder holds app data, settings and caches as well as documents, so watching it would put all of them in Nordvec. Its name is also your computer account name. **Workaround:** Add Documents, Desktop or another folder inside your home folder instead. ### A folder inside or around a watched folder cannot be added [#a-folder-inside-or-around-a-watched-folder-cannot-be-added] What you see: **This folder overlaps with a folder you are already watching.** **Cause:** A file in two watched folders would have two owners, and an exclusion set on one folder would not apply through the other. **Workaround:** Files in a folder inside a watched folder already sync, so there is nothing to add. To watch a wider folder instead, stop watching the narrower one first: its documents leave Nordvec until the wider folder syncs them again. ## Files that are not synced [#files-that-are-not-synced] These files stay on your computer and are listed on the Desktop sync page with the reason, so answers cannot cite them. ### A file's path is too long [#a-files-path-is-too-long] What you see: **The path is too long for this system** **Cause:** The full path is longer than this operating system lets the app read. **Workaround:** Shorten the folder or file names, or move the folder closer to the top of the drive. The file syncs once its path is short enough. ### A file could not be read [#a-file-could-not-be-read] What you see: **This file could not be read** **Cause:** The operating system refused the app read access to the file. **Workaround:** Give your user account read access to the file. On macOS, allow Nordvec Desktop under System Settings, Privacy & Security, Files and Folders. The app reads the file again when it changes and each time the app starts. ### An item is not an ordinary file [#an-item-is-not-an-ordinary-file] What you see: **This is not an ordinary file** **Cause:** It is a symbolic link, a device, a pipe or another special file. The app reads ordinary files only, so a link can never lead it to a file you did not pick. **Workaround:** Add the folder that holds the real file instead of the link. ### A file has more than one name on disk [#a-file-has-more-than-one-name-on-disk] What you see: **This file has more than one name on disk** **Cause:** The file is a hard link: the same data has a second name, which can sit outside the folder you chose. The app cannot tell which folder the data belongs to, so it does not read it. Backup tools that save space this way produce such files. **Workaround:** Replace the file with a plain copy of it, which has one name. ### A file leads outside the watched folder [#a-file-leads-outside-the-watched-folder] What you see: **This file leads outside the watched folder** **Cause:** The file's path resolves, through a link or a junction, to a place outside the folder you chose. **Workaround:** Add the folder the file really lives in. ### A file is inside a folder you excluded [#a-file-is-inside-a-folder-you-excluded] What you see: **This file is inside a folder you excluded** **Cause:** You excluded a subfolder of a watched folder, and a file you pick inside it stays excluded. **Workaround:** Turn the subfolder back on in the folder's card on the Desktop sync page, and its files sync. ### A file is larger than the limit for its type [#a-file-is-larger-than-the-limit-for-its-type] What you see: **This file is larger than the limit for its type** **Cause:** Each file type has a size limit, checked before the file is read. If an earlier, smaller version was synced, its copy is removed so answers never cite content the file no longer has. **Workaround:** Split the file into smaller files, or save it in a more compact format. ### A file is empty [#a-file-is-empty] What you see: **This file is empty, so there is nothing to search** **Cause:** A file with no content has nothing to search. If an earlier version had content, its copy is removed for the same reason as an oversized one. **Workaround:** Nothing to do: the file syncs once it has content. ### A file type cannot be searched [#a-file-type-cannot-be-searched] What you see: **This file type cannot be searched** **Cause:** The file's extension is not one the app syncs. **Workaround:** Save or export the file as one of the types in the size-limit table at the end of this page. ### A file could not be added [#a-file-could-not-be-added] What you see: **This file could not be added** **Cause:** Reading the file failed for a reason other than the ones above, for example because it changed or was locked while the app read it. **Workaround:** Close whatever has the file open. The app reads the file again when it changes and each time the app starts. If the same file keeps failing, report it with your log file attached. ## Removals that wait for you [#removals-that-wait-for-you] Nothing is removed from Nordvec while the app cannot tell a deletion from a folder that is only out of reach. ### Many files deleted at once stay in Nordvec until you confirm [#many-files-deleted-at-once-stay-in-nordvec-until-you-confirm] What you see: **Large deletion held for review** **Cause:** When more than 25% of a folder's files disappear within 7 days (in a folder of at least 20 files), the app holds their removal from Nordvec instead of carrying it out, because a moved or unplugged folder looks the same as a deletion. **Workaround:** Confirm the removal on the folder's card on the Desktop sync page, or put the files back. A held removal you do not confirm is carried out on the date the page shows. ### A folder that cannot be read keeps its documents in Nordvec [#a-folder-that-cannot-be-read-keeps-its-documents-in-nordvec] What you see: **A synced folder is missing** **Cause:** When a watched folder cannot be read at all, for example on a disconnected drive or network share, the app treats it as unreachable rather than empty and removes nothing. **Workaround:** Reconnect the drive, and syncing resumes. To remove the folder's documents from Nordvec, stop watching the folder. ## Documents that leave Nordvec [#documents-that-leave-nordvec] A document in Nordvec follows its file on your computer. These are the two ways one is removed. ### A document left Nordvec after its file was moved, renamed or deleted [#a-document-left-nordvec-after-its-file-was-moved-renamed-or-deleted] **Cause:** A document is in Nordvec because its file is in a watched folder. When the file is deleted or moved out of the folder, its copy is removed. A renamed or moved file is a new path, so it syncs again as a new document. **Workaround:** Put the file back, or wait for the moved file to sync. A file that is back on disk before its removal runs keeps its document. ### Documents left Nordvec after you stopped watching or excluded a folder [#documents-left-nordvec-after-you-stopped-watching-or-excluded-a-folder] **Cause:** Stopping watching a folder, or excluding a subfolder, removes its documents from Nordvec. The files on your computer are not touched. **Workaround:** Add the folder again, or remove the exclusion, and its files sync again. ## When sync is off [#when-sync-is-off] Each of these stops syncing for the signed-in account until it is fixed, and the app says which one it is. ### Sync is off because the computer has no keyring [#sync-is-off-because-the-computer-has-no-keyring] What you see: **Nordvec encrypts your local sync data with a key from your system keyring, and this computer has none available. Install and unlock a keyring (gnome-keyring or kwallet), then sign in again.** **Cause:** The app encrypts its local sync data with a key the operating system's keychain protects, and never falls back to storing file names unencrypted. On Linux without a running gnome-keyring or KWallet there is no keychain to hold the key. **Workaround:** Install and unlock gnome-keyring or KWallet, then sign in again. ### Sync is off because a newer version wrote the local data [#sync-is-off-because-a-newer-version-wrote-the-local-data] What you see: **Your sync data was written by a newer version of Nordvec. Update the app to resume syncing.** **Cause:** The local sync data was written by a newer version of the app, usually because an older version was installed over it. **Workaround:** Install the latest version. ### Sync is off because the local sync data cannot be read [#sync-is-off-because-the-local-sync-data-cannot-be-read] What you see: **Your local sync state could not be read. Syncing is paused; reinstalling may be required.** **Cause:** The sync store could not be opened or read, for example because the file is damaged or its key cannot be unlocked by this user account. **Workaround:** Report it with your log file attached. Do not delete the data directory first: it can hold removals that have not reached Nordvec yet. ## File size limits [#file-size-limits] The app syncs these file types, each up to the size shown. A larger file is listed as too large, and a type not in this table as one that cannot be searched. | Largest file | File types | | ------------ | ------------------------------------------------------------------ | | 50 MB | `.csv`, `.docx`, `.htm`, `.html`, `.pdf`, `.pptx`, `.xls`, `.xlsx` | | 20 MB | `.json`, `.xml` | | 15 MB | `.gif`, `.jpeg`, `.jpg`, `.png`, `.svg`, `.webp` | | 10 MB | `.md`, `.txt` | | 5 MB | `.js`, `.jsx`, `.py`, `.sql`, `.ts`, `.tsx` |