CoraleVault CoraleVault - Free Open Source Password Manager v2025.11.6

Troubleshooting Guide

Solutions to common problems with CoraleVault

Troubleshooting Guide

This guide helps you diagnose and fix common problems with CoraleVault. If you can’t find a solution here, see Getting Help at the bottom.

Application Won’t Start

Windows: Application Crashes on Startup

Symptoms: Double-clicking CoraleVault.exe causes a brief window flash or error dialog.

Solutions:

  1. Check for missing DLL files

  2. Run as Administrator

    • Right-click CoraleVault.exe → “Run as administrator”
    • If this fixes it, set it permanently:
      • Right-click → Properties → Compatibility tab
      • Check “Run this program as an administrator”

  3. Check antivirus/firewall

    • Some antivirus software blocks unsigned executables
    • Add CoraleVault.exe to your antivirus whitelist
    • Temporarily disable antivirus to test

  4. Check Windows version

    • CoraleVault requires Windows 7 or later
    • Windows 10/11 is strongly recommended
    • Run winver to check your version

  5. Reinstall

    • Uninstall completely
    • Download fresh installer from /download/
    • Install to default location (C:\Program Files\CoraleVault)

macOS: “App can’t be opened because it is from an unidentified developer”

Solution 1: Right-click method (RECOMMENDED)

  1. Right-click “CoraleVault” in Applications
  2. Click “Open”
  3. Click “Open” again in the dialog
  4. macOS will remember this choice

Solution 2: Remove Gatekeeper quarantine

1

xattr -cr "/Applications/CoraleVault.app"

Solution 3: System Preferences

  1. System Preferences → Security & Privacy → General
  2. Look for message about “CoraleVault was blocked”
  3. Click “Open Anyway”

macOS: Application crashes on startup

Check Console for errors:

  1. Open Console app (Applications → Utilities → Console)
  2. Search for “CoraleVault”
  3. Look for crash reports

Common fixes:

1
2
3
4
5
6
7
8

# Fix permissions
sudo chmod -R 755 "/Applications/CoraleVault.app"

# Reinstall wxWidgets (if building from source)
brew reinstall wxwidgets

# Check for library conflicts
otool -L "/Applications/CoraleVault.app/Contents/MacOS/CoraleVault"

Linux: Application won’t start

Check for missing dependencies:

Ubuntu/Debian:

1

sudo apt-get install libgtk-3-0 libwxgtk3.0-gtk3-0v5 libstdc++6

Fedora/RHEL:

1

sudo dnf install gtk3 wxGTK3 libstdc++

Run from terminal to see errors:

1
2
3

corale-vault
# Or if using AppImage:
./CoraleVault-2025.11.5-x86_64.AppImage

Check for library conflicts:

1
2

ldd /usr/bin/corale-vault
# Look for "not found" errors

AppImage FUSE issues:

1
2
3
4
5
6
7
8

# Install FUSE if missing
sudo apt-get install fuse libfuse2  # Ubuntu/Debian
sudo dnf install fuse fuse-libs     # Fedora

# Or extract and run directly
./CoraleVault-2025.11.5-x86_64.AppImage --appimage-extract
cd squashfs-root
./AppRun

Cannot Open Vault File

Error: “Failed to open file” or “File not found”

Solutions:

  1. Verify file exists

    • Navigate to the folder in File Explorer
    • Confirm the .vault file is there
    • Check file name matches exactly (case-sensitive on macOS/Linux)

  2. Check file permissions

    • Windows: Right-click → Properties → Security → Make sure you have “Read” permission
    • macOS/Linux: ls -la filename.vault (should show read permissions)
    • Fix: chmod 644 filename.vault (macOS/Linux)

  3. File is locked by another program

    • Close all CoraleVault windows
    • Check Task Manager (Windows) or Activity Monitor (macOS) for lingering processes
    • Reboot if necessary

  4. File is on network drive or cloud storage

    • Network interruptions can cause issues
    • Copy vault file to local drive temporarily
    • Try opening the local copy

  5. File path contains special characters

    • Avoid: < > : " / \ | ? * in file names
    • Avoid non-English characters in path
    • Rename to simple ASCII: passwords.vault

Error: “Invalid file format” or “Not a valid vault file”

Causes:

  • File is corrupted
  • File is not actually a CoraleVault file
  • File was partially transferred (incomplete download/copy)

Solutions:

  1. Check file size

    • Minimum vault file: ~500 bytes
    • If file is 0 bytes or suspiciously small, it’s corrupted

  2. Check file header

    • Windows: certutil -hashfile passwords.vault SHA256
    • macOS/Linux: head -c 20 passwords.vault | xxd
    • Valid vault files start with binary header

  3. Restore from backup

  4. Try opening in older version

    • If you recently upgraded, try previous version
    • Download from GitHub Releases

Error: “Incorrect password”

See Forgot Master Password below.

Forgot Master Password

The Hard Truth

There is NO password recovery. This is not a bug—it’s the most important security feature.

Why no recovery?

  • Master password is never stored (not even encrypted)
  • Your data is encrypted with keys derived from the password
  • Without the password, decryption is mathematically impossible
  • Even we (the developers) cannot access your vault

What this means:

  • If you forget your master password, your data is lost forever
  • There is no “reset password” option
  • There is no “security questions” backdoor
  • There is no recovery service

What You Can Try

  1. Try variations you might have used

    • Common typos
    • Different capitalization
    • With/without numbers or symbols
    • Old passwords you reused

  2. Check if you wrote it down

    • Password notebook
    • Secure physical location (safe, drawer)
    • Emergency contact might have copy

  3. Search your computer for clues

    • Notes apps
    • Password hints (if you left any)
    • DO NOT search for actual password in plain text files (security risk)

  4. Restore from old backup

    • If you have a backup from when you remembered the password
    • Old cloud sync versions (Dropbox, Google Drive have version history)

Prevention for Next Time

  1. Write down master password on paper

    • Store in safe, locked drawer, or safety deposit box
    • Give copy to trusted family member

  2. Use a memorable passphrase

    • Not a random password (easier to remember)
    • Example: Correct-Horse-Battery-Staple-2025!
    • See Getting Started Guide

  3. Practice typing it

    • Type it 10 times when you first create it
    • Muscle memory helps

  4. Don’t change master password too often

    • Only change if compromised
    • Each change is a risk of forgetting

Corrupted Vault File

Symptoms

  • “Invalid file format” error
  • Application crashes when opening vault
  • Garbled data or missing entries
  • File size is 0 bytes or much smaller than expected

Causes

  • Hard drive failure or bad sectors
  • Application crash during save
  • Incomplete file transfer
  • Cloud sync conflict
  • Antivirus quarantine/repair

Recovery Steps

Step 1: Restore from Backup

This is why backups are critical! See Backup & Recovery Guide.

Where to find backups:

  • Manual backups (external drives, USB)
  • Cloud storage (Dropbox, Google Drive, OneDrive)
  • Cloud version history (if file was synced)
  • System backup (Time Machine, Windows Backup)

Restoring from cloud version history:

Dropbox:

  1. Right-click file → Version history
  2. Select previous version before corruption
  3. Download and test

Google Drive:

  1. Right-click file → Manage versions
  2. Download earlier version

OneDrive:

  1. Right-click file → Version history
  2. Restore previous version

Step 2: Check for Temporary Files

CoraleVault may have created temporary backup during last save:

Windows:

  • Same folder as vault: passwords.vault.tmp, passwords.vault.bak
  • Temp folder: C:\Users\YourName\AppData\Local\Temp

macOS:

  • Same folder: passwords.vault.tmp, passwords.vault.bak
  • Temp: /tmp/ (automatically cleared on reboot)

Linux:

  • Same folder: passwords.vault.tmp, passwords.vault.bak
  • Temp: /tmp/

Try opening these files directly (rename to .vault extension first).

Step 3: File System Recovery

Windows:

1
2
3
4
5
6
7
8
9

# Check disk for errors
chkdsk C: /f

# Try file recovery
C:\> dir /a passwords.vault*
# Look for .tmp or .bak files

# Use File History (if enabled)
Right-click file → Restore previous versions

macOS:

1
2
3
4
5

# Check Time Machine
Browse Time Machine backups in vault folder

# Check for .vault~ files
ls -la ~/Documents/*.vault*

Linux:

1
2
3
4
5
6

# Check for backup files
ls -la ~/.vault*

# Try PhotoRec (file recovery tool)
sudo apt-get install testdisk
photorec

Step 4: Data Recovery Software

If no backups exist and file is corrupted, try data recovery tools:

Free tools:

  • Recuva (Windows)
  • TestDisk/PhotoRec (All platforms)
  • Disk Drill (Free trial)

These might recover older versions of the file from disk.

Prevention

  1. Multiple backups (3-2-1 rule)

    • 3 copies total
    • 2 different media (drive + cloud)
    • 1 off-site (cloud or different location)

  2. Cloud storage with versioning

    • Dropbox keeps 30 days of history
    • Google Drive keeps 30 days
    • OneDrive keeps version history

  3. Regular manual backups

    • Weekly: Copy to external drive
    • Monthly: Copy to different location

  4. Don’t edit vault on unstable storage

    • Avoid network drives
    • Don’t use vault from USB drive directly (copy to local first)

Performance Issues

Application is slow to open vault

Cause: Large vault files (1000+ entries) or slow hard drive.

Solutions:

  1. Move vault to SSD

    • HDDs are much slower for random access
    • SSD reduces open time significantly

  2. Close other programs

    • Free up RAM
    • Reduce CPU load

  3. Defragment hard drive (Windows HDD only)

    • Don’t defragment SSDs
    • Windows: defrag C: /O

  4. Check system resources

    • Task Manager (Windows) or Activity Monitor (macOS)
    • Look for high CPU or memory usage

Searching is slow

Cause: Large vault (1000+ entries).

Solutions:

  1. Use groups to organize

    • Filter by group before searching
    • Reduces search scope

  2. Upgrade system RAM

    • Minimum 4 GB recommended for large vaults
    • 8 GB+ ideal

Application uses too much RAM

Normal RAM usage:

  • Small vault (< 100 entries): 50-150 MB
  • Medium vault (100-500 entries): 150-300 MB
  • Large vault (500-1000 entries): 300-500 MB
  • Very large vault (1000+ entries): 500 MB - 1 GB

If using much more:

  1. Restart application
  2. Check for memory leaks (report bug)
  3. Split vault into multiple files

Import/Export Problems

Import fails with “Invalid CSV format”

Solutions:

  1. Check CSV encoding

    • Must be UTF-8
    • Open in text editor, save as UTF-8

  2. Check CSV structure

    • Must have header row: Title,Username,Password,URL,Notes,Group
    • Commas must be properly escaped
    • Quotes around fields with commas

  3. Check for special characters

    • Some password managers export with strange encoding
    • Try opening CSV in Excel/LibreOffice first
    • Re-save as clean UTF-8 CSV

  4. Split large imports

    • If importing 1000+ entries, split into multiple files
    • Import in batches

Export creates empty file

Solutions:

  1. Check file permissions

    • Export location must be writable
    • Try exporting to Desktop or Documents

  2. Check disk space

    • Large vaults need significant disk space
    • Ensure 100+ MB free

  3. Vault must be unlocked

    • Cannot export from locked vault

Imported entries have garbled text

Cause: Encoding mismatch.

Solutions:

  1. Re-export from source with UTF-8

    • Chrome: Export as UTF-8 CSV
    • Excel: Save As → CSV UTF-8

  2. Convert encoding

    • Open CSV in Notepad++
    • Encoding → Convert to UTF-8
    • Save

Platform-Specific Issues

Windows

“VCRUNTIME140.dll not found”

Solution: Install Visual C++ Redistributable

Antivirus keeps deleting CoraleVault.exe

Solution:

  1. Restore file from Quarantine
  2. Add to whitelist/exclusions
  3. File is safe (check VirusTotal)

Windows SmartScreen blocks installer

This is expected (app is not code-signed).

Solution:

  1. Click “More info”
  2. Click “Run anyway”
  3. Verify download from official source

macOS

“Damaged and can’t be opened”

Solution:

1

xattr -cr "/Applications/CoraleVault.app"

Copy/paste doesn’t work

Check accessibility permissions:

  1. System Preferences → Security & Privacy → Privacy tab
  2. Accessibility → Add “CoraleVault”

Shortcuts don’t work (Cmd+C, Cmd+V)

Check keyboard permissions:

  1. System Preferences → Security & Privacy → Privacy tab
  2. Input Monitoring → Add “CoraleVault”

Linux

AppImage won’t run: “No such file or directory”

Install FUSE:

1
2
3
4
5

# Ubuntu/Debian
sudo apt-get install fuse libfuse2

# Fedora
sudo dnf install fuse fuse-libs

Icon doesn’t appear in application menu

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Install .desktop file manually
mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/corale-vault.desktop << 'EOF'
[Desktop Entry]
Name=CoraleVault
Exec=/path/to/CoraleVault-2025.11.5-x86_64.AppImage
Icon=corale-vault
Type=Application
Categories=Utility;Security;
EOF

Clipboard doesn’t work

Install clipboard manager:

1
2
3
4
5

# Ubuntu/Debian
sudo apt-get install xclip

# Fedora
sudo dnf install xclip

Error Messages

“Failed to decrypt vault”

Causes:

  • Incorrect master password
  • Vault file corrupted
  • Wrong encryption algorithm (very old vault)

Solutions:

  1. Re-enter password carefully (check Caps Lock)
  2. Try variations of password
  3. Restore from backup
  4. Try opening in older version of CoraleVault

“Out of memory”

Causes:

  • Very large vault (10,000+ entries)
  • System RAM too low
  • Memory leak (bug)

Solutions:

  1. Close other programs
  2. Restart application
  3. Upgrade system RAM
  4. Split vault into multiple files
  5. Report bug with vault size details

“Access denied” or “Permission denied”

Causes:

  • File permissions
  • File in use by another program
  • Antivirus blocking

Solutions:

  1. Run as administrator (Windows) or with sudo (Linux)
  2. Check file permissions
  3. Close other CoraleVault instances
  4. Disable antivirus temporarily

“Failed to save vault”

Causes:

  • Disk full
  • File permissions
  • Network drive disconnected
  • Antivirus interference

Solutions:

  1. Check disk space
  2. Save to different location
  3. Check file isn’t read-only
  4. Disable antivirus temporarily

Getting Help

Before Reporting a Bug

  1. Update to latest version

  2. Check existing issues

  3. Gather information

    • Operating system and version
    • CoraleVault version
    • Exact error message
    • Steps to reproduce

How to Report a Bug

Open a GitHub issue: https://github.com/Coralesoft/CoraleVault/issues/new

Include:

  1. Title: Brief description (e.g., “Cannot open vault on Windows 11”)
  2. Environment:
    • OS: Windows 11 Pro 23H2
    • CoraleVault version: 2025.11.5
    • Installation method: Installer / Portable / AppImage
  3. Steps to reproduce:
    • What you did
    • What you expected
    • What actually happened
  4. Error messages: Copy exact text
  5. Screenshots: If applicable
  6. Vault details (DO NOT share actual vault file):
    • Approximate size
    • Number of entries
    • Created with which version

Get Support

Emergency Data Recovery

If you’ve lost access to your passwords:

  1. Check all backups thoroughly
  2. Try password variations systematically
  3. Contact us - We’ll try to help (but cannot guarantee recovery)
  4. Learn for next time - See Backup Guide

Additional Resources

Can’t find a solution? Contact support or open an issue.