Error Handling

Necron Vault Manager is designed to fail safely — when something goes wrong, the app provides clear error messages and never silently corrupts data. This page catalogs common errors, their causes, and how to resolve them.

Error Categories

Errors in Necron Vault Manager fall into several categories:

Key & Dongle Errors

No Dongle Connected

Message: "No encryption key available"

Cause: No USB dongle is inserted, and no Free Tier login is active.

Solution:

1. Insert your Necron USB dongle
2. Wait 2–3 seconds for detection
3. If not detected, try a different USB port or trigger a manual scan
4. Alternatively, log in through the "Enter Free Tier" form on the Gatekeeper screen

Key UID Mismatch

Message: "Key UID mismatch — the connected dongle does not match this file"

Cause: You're trying to decrypt a file that was encrypted with a different dongle. The key identifier in the encrypted file doesn't match any connected dongle.

Solution:

1. Check which dongle the file was encrypted with (the error may display the expected key identifier)
2. Connect the correct MASTER or SLAVE dongle
3. If you have multiple dongles, try each one
4. If the original dongle is lost and you don't have a SLAVE backup, the file cannot be recovered

Corrupt Key Header

Message: "Invalid key file — corrupt or unrecognized header"

Cause: The .dat file on the dongle has been corrupted or is not a valid Necron key file.

Solution:

1. Try the dongle on another USB port
2. Check if the dongle works on a different computer
3. Verify the .dat file exists and has the expected size
4. If the key file is corrupt, you'll need a backup dongle or re-provisioning

SLAVE Key — Operation Not Permitted

Message: "This operation requires a MASTER key"

Cause: You're trying to perform a write operation (encrypt, create vault, modify vault) with a SLAVE (read-only) dongle.

Solution:

• Connect your MASTER dongle for write operations
• SLAVE dongles can only decrypt files and import vaults

Pad Errors

Pad Exhausted

Message: "Pad exhausted — not enough key material remaining"

Cause: Your dongle's one-time pad has been fully consumed. There are no more unused bytes available for encryption.

Solution:

• For NCV3 format: NCV3 uses only 64 bytes of pad per file, so this is rare. Check if there's a pad accounting issue.
• For legacy OTP1 format: OTP1 consumes pad bytes 1:1 with file size, so large files exhaust the pad quickly.
• Upgrade to a new dongle with fresh key material
• Consider re-provisioning through your Necron account

Reservation Failed

Message: "Failed to reserve pad range"

Cause: The key material reservation system encountered an error while trying to allocate space on the dongle.

Solution:

1. Check that the dongle is properly connected (not intermittent)
2. Try a different USB port
3. Try a manual rescan and retry the operation

Encryption Errors

File Read Error

Message: "Cannot read source file"

Cause: The source file is locked by another program, doesn't exist, or you don't have read permissions.

Solution:

1. Close any programs that might have the file open
2. Check that the file still exists at the expected path
3. Verify you have read permissions on the file

Destination Write Error

Message: "Cannot write to destination"

Cause: The output directory is read-only, full, or doesn't exist.

Solution:

1. Check that the destination folder exists and is writable
2. Verify there's enough free disk space
3. If writing to a network drive, check connectivity

File Too Large for Pad

Message: "File size exceeds available pad"

Cause: The file you're encrypting is larger than the remaining pad (primarily an issue with OTP1 format).

Solution:

• Switch to NCV3 format, which uses vastly less pad per file
• Encrypt a smaller file
• Use a dongle with more remaining pad

Decryption Errors

Authentication Failed

Message: "Authentication tag verification failed — file may be corrupted or tampered with"

Cause: The AEAD authentication tag doesn't match. This means:

• The encrypted file was modified after encryption (data corruption or tampering)
• The wrong key is being used (different dongle)
• The file was truncated or partially overwritten

Solution:

1. Verify you're using the correct dongle
2. Check if the encrypted file was accidentally modified (compare file size with expected)
3. If the file was stored in a cloud-synced folder, check for sync conflicts
4. If the file is genuinely corrupted, try restoring from a backup

Unsupported Format

Message: "Unrecognized file format — invalid magic bytes"

Cause: The file doesn't have a recognized Necron header (NCV3, NCV2, OTP1, or NECN).

Solution:

• Verify the file is actually a Necron-encrypted file
• Check that the file extension is correct (.ncv3, .ncrn)
• The file may have been corrupted, particularly the header bytes

Anti-Rename Detection

Message: "Filename token mismatch — file may have been renamed"

Cause: The on-disk filename doesn't match what's stored inside the encrypted file. This happens when someone renames a .ncrn file on disk.

Solution:

1. Rename the file back to its original encrypted name
2. If you don't know the original name, the file may not be recoverable through normal means

Vault Errors

Vault Unlock Failed

Message: "Cannot unlock vault — dongle not available"

Cause: The vault requires a specific dongle that isn't connected.

Solution: Connect the correct MASTER or SLAVE dongle.

Integrity Check Failures

Message: "Integrity check found N damaged files"

Cause: The vault integrity check detected encrypted files with invalid verification tags or corrupted headers across one or more locations.

Solution:

• If other locations have good copies, the app will automatically repair by copying from the good source
• If all copies of a file are damaged, the file may not be recoverable
• Check your disk and cloud sync for corruption issues

See Vault Integrity Check for the full integrity and self-healing workflow.

Metadata Sync Failed

Message: "Failed to write vault snapshot"

Cause: The app couldn't write a vault configuration snapshot to a vault location.

Solution:

1. Check that the vault location is writable
2. If it's a cloud-synced folder, check that the sync client isn't locking files
3. This is a best-effort operation — the vault still functions without it, but backup dongle import may not have the latest state

File System Errors

Path Too Long

Message: "Path exceeds maximum length"

Cause: The file path exceeds Windows' MAX_PATH (260 characters). This can happen with deeply nested vault directories or long filenames.

Solution:

• The app uses Windows extended-length paths (\\?\) internally to handle long paths
• If you're seeing this error, check for unusually deep directory nesting
• Move the vault to a shorter base path if needed

Permission Denied

Message: "Access denied"

Cause: The app doesn't have permission to read from or write to the specified location.

Solution:

1. Check file/folder permissions in Windows Security
2. If the file is on a network share, verify your access level
3. Ensure you have write access to the destination directory

Disk Full

Message: "Not enough disk space"

Cause: The destination drive doesn't have enough free space for the operation.

Solution:

1. Free up disk space
2. Choose a different destination with more space
3. For batch operations, check that the destination can hold all output files

Getting Help

If you encounter an error not listed here:

1. Note the exact error message and the operation you were performing
2. Check the Troubleshooting & FAQ page
3. Contact Necron support with the error details