Common FileFortress Issues and Solutions

Troubleshoot installation, connection, and performance issues

Symptoms: 'filefortress' is not recognized as an internal or external command

Solutions:

1. Restart your terminal/PowerShell window
2. Verify installation path is in PATH environment variable
3. Try running with full path: C:\Program Files\FileFortress\filefortress.exe
4. Reinstall using administrator privileges

Symptoms: bash: filefortress: command not found

Solutions:

1. Verify installation: which filefortress
2. Check if binary is in PATH: echo $PATH
3. Add to PATH if needed: export PATH=$PATH:/usr/local/bin
4. Make binary executable: chmod +x /usr/local/bin/filefortress

Symptoms: Permission denied when running commands

Solutions:

1. Check file permissions: ls -l ~/.filefortress/
2. Fix permissions: chmod 600 ~/.filefortress/*
3. Ensure you own the files: chown $USER ~/.filefortress/*

Symptoms: Authentication failed or Invalid password

Solutions:

1. Verify you're using the correct password
2. Check key file path is correct: --key-file ~/filefortress.key
3. Verify key file contains the password (check file size)
4. Try password directly instead of key file
5. If all else fails, reinitialize (loses local database)

Symptoms: Device not registered or Invalid registration code

Solutions:

1. Verify you've run filefortress init
2. Check registration code is valid (get new one from web portal)
3. If device was removed from portal, use filefortress reinit --code NEW_CODE
4. Ensure you're logged into the web portal

Symptoms: Registration code has expired

Solutions:

1. Generate new registration code from web portal
2. Registration codes expire after 24 hours
3. Use new code immediately after generation

Symptoms: Connection failed or Network error

Solutions:

1. Check internet connection: ping google.com
2. Verify firewall isn't blocking FileFortress
3. Check proxy settings if behind corporate proxy
4. Try again later (provider may be experiencing issues)
5. Check provider status page (e.g., status.cloud.google.com)

Symptoms: Browser opens but authentication doesn't complete

Solutions:

1. Ensure you're logged into correct account in browser
2. Clear browser cookies and try again
3. Try different browser
4. Check if popup blocker is interfering
5. Manually copy callback URL if automatic detection fails

Symptoms: SSL certificate verification failed

Solutions:

1. Update system certificates: sudo update-ca-certificates (Linux)
2. Check system time is correct
3. Verify you're not behind SSL-inspecting proxy
4. Update FileFortress to latest version

Symptoms: Scan doesn't complete, hangs indefinitely

Solutions:

1. Check network connection stability
2. Scan smaller remotes individually instead of --all
3. Increase timeout if available in config
4. Check provider rate limits (may be throttling)
5. Try during off-peak hours

Symptoms: Permission denied or Access forbidden

Solutions:

1. Verify you have read permissions for the remote
2. Re-authenticate: filefortress remotes add [type]
3. Check if OAuth token has expired
4. Verify account has necessary permissions

Symptoms: Scan completes but shows 0 files

Solutions:

1. Verify remote actually contains files
2. Check if scanning correct remote: filefortress remotes list
3. Verify authentication is working
4. Check if remote path/bucket is correct
5. Try removing and re-adding remote

Symptoms: Rate limit exceeded or Too many requests

Solutions:

1. Wait before retrying (rate limits reset after time period)
2. Reduce scan frequency
3. Scan during off-peak hours
4. Check provider's rate limit documentation
5. Consider upgrading provider plan for higher limits

Symptoms: Search completes but shows no files

Solutions:

1. Verify you've scanned remotes: filefortress remotes list
2. Check if search query is too specific
3. Try broader search: filefortress search "" (all files)
4. Verify files exist in cloud storage
5. Rescan if files were added recently

Symptoms: Search shows files that no longer exist or misses new files

Solutions:

1. Run fresh scan: filefortress remotes scan --all
2. Set up automated scanning (see Automation Guide)
3. Check last scan time: filefortress remotes list

Symptoms: --meta filters return no results

Solutions:

1. Verify files have the metadata you're filtering by
2. Check metadata syntax: --meta "key=value"
3. For EXIF data, ensure files are photos
4. For hashes, run enrichment: filefortress remotes enrich
5. Try --meta "key exists" to check if metadata is present

Symptoms: Scans take very long time

Solutions:

1. Check network speed
2. Scan remotes individually instead of --all
3. Skip enrichment if not needed (hashes, metadata)
4. Check provider rate limits
5. Consider scanning during off-peak hours
6. Verify no other bandwidth-intensive processes running

Symptoms: Search queries take long time

Solutions:

1. Use more specific filters to reduce result set
2. Filter by remote: --remote-name "Google Drive"
3. Filter by file type: --media-type image
4. Check database size (may need optimization)
5. Use saved queries for complex searches

Symptoms: FileFortress uses excessive memory

Solutions:

1. Close other applications
2. Scan remotes individually instead of all at once
3. Limit search results with pagination
4. Check for memory leaks (update to latest version)

Symptoms: Database file is very large

Solutions:

1. This is normal for large file collections
2. Database stores metadata for all scanned files
3. Consider removing old remotes you no longer use
4. Enrichment (hashes) increases database size