noentropy/docs/TROUBLESHOOTING.md

Troubleshooting Guide

This guide helps you solve common issues you might encounter while using NoEntropy.

Configuration Issues

"API key not configured"

Problem: NoEntropy cannot find your Gemini API key.

Solutions:

1. Interactive Setup (Recommended):

   • Simply run NoEntropy and it will prompt you for your API key
   • The configuration will be saved automatically

2. Manual Configuration:

   mkdir -p ~/.config/noentropy
   nano ~/.config/noentropy/config.toml
   

   Add:

   api_key = "your_actual_api_key_here"
   download_folder = "/home/user/Downloads"
   

3. Use Change Key Flag:

   ./noentropy --change-key
   

Verify: Run ./noentropy --dry-run to test your configuration.

---

"Download folder not configured"

Problem: NoEntropy doesn't know which folder to organize.

Solutions:

1. Interactive Setup:

   • Run NoEntropy and it will prompt you for the folder path
   • It will suggest a default location based on your system

2. Manual Configuration:

   nano ~/.config/noentropy/config.toml
   

   Add or update:

   download_folder = "/path/to/your/Downloads"
   

Important: Use absolute paths, not relative paths (e.g., /home/user/Downloads, not ~/Downloads).

---

"Configuration file not found"

Problem: The configuration file doesn't exist or is in the wrong location.

Expected Locations:

• Linux/macOS: ~/.config/noentropy/config.toml
• Windows: C:\Users\<username>\AppData\Roaming\noentropy\config.toml

Solutions:

1. Create configuration directory:

   mkdir -p ~/.config/noentropy
   

2. Copy example configuration:

   cp config.example.toml ~/.config/noentropy/config.toml
   

3. Edit configuration:

   nano ~/.config/noentropy/config.toml
   

---

"Invalid API key format"

Problem: Your API key is incorrectly formatted or invalid.

Solutions:

1. Get a new API key:

   • Visit Google AI Studio
   • Create a new API key
   • Copy it exactly (including all characters)

2. Check for common issues:

   • No extra spaces before or after the key
   • Key is enclosed in quotes in TOML file
   • No line breaks within the key

Example of correct format:

api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k"

---

API and Network Issues

"API rate limit exceeded"

Problem: You're making too many requests to the Gemini API.

Solutions:

1. Wait and retry:

   • Wait 5-10 minutes before trying again
   • Rate limits reset over time

2. Reduce concurrency:

   ./noentropy --max-concurrent 2
   

3. Use caching:

   • NoEntropy caches results for 7 days
   • Subsequent runs of same files won't hit API
   • Cache is automatic, no configuration needed

4. Check API quota:

   • Visit Google AI Studio
   • Check your API usage and quotas
   • Consider upgrading if you hit limits frequently

---

"Network error" or "Connection timeout"

Problem: Cannot connect to Gemini API.

Solutions:

1. Check internet connection:

   ping google.com
   

2. Verify API service status:

   • Check Google Cloud Status
   • Verify Gemini API is operational

3. Check firewall settings:

   • Ensure outbound HTTPS (port 443) is allowed
   • Whitelist generativelanguage.googleapis.com if needed

4. Try with fewer files:

   • API timeout might be due to large batch
   • Reduce --max-concurrent value
   • Organize files in smaller batches

5. Check proxy settings:

   • If behind corporate proxy, configure proxy settings
   • Some proxies block API calls

---

"Invalid API response" or "Failed to parse response"

Problem: API returned unexpected or malformed data.

Solutions:

1. Retry the operation:

   • Temporary API glitch might resolve itself
   • Run NoEntropy again

2. Check API key validity:

   • API key might have been revoked
   • Create a new API key

3. Clear cache and retry:

   rm .noentropy_cache.json
   ./noentropy
   

4. Report issue:

   • If problem persists, it might be a bug
   • Check GitHub Issues

---

File Operation Issues

"Failed to move file" or "Permission denied"

Problem: Cannot move files to destination folder.

Solutions:

1. Check file permissions:

   ls -la /path/to/file
   

2. Check destination permissions:

   ls -la /path/to/Downloads
   

3. Fix permissions:

   chmod 644 /path/to/file  # For files
   chmod 755 /path/to/directory  # For directories
   

4. Run as appropriate user:

   • Don't run as root unless necessary
   • Ensure you own the files and folder

5. Check disk space:

   df -h /path/to/Downloads
   

---

"File not found" or "Source file doesn't exist"

Problem: Files were deleted or moved before organization completed.

Solutions:

1. Verify files exist:

   ls -la /path/to/Downloads
   

2. Check if another process is moving files:

   • Browser might be cleaning up
   • Another organization tool might be running
   • Antivirus might have quarantined files

3. Use dry-run first:

   ./noentropy --dry-run
   

   • This ensures files exist before actual move

---

"Destination already exists" or "File conflict"

Problem: A file with the same name already exists at destination.

Solutions:

1. Current behavior: NoEntropy will skip the file to prevent overwrites

2. Manual resolution:

   • Rename the existing file
   • Delete the existing file if not needed
   • Run organization again

3. Check for duplicates:

   • You might have duplicate downloads
   • Consider cleaning duplicates manually

---

Cache Issues

"Cache corrupted" or "Failed to read cache"

Problem: Cache file is corrupted or malformed.

Solutions:

1. Delete cache file:

   rm .noentropy_cache.json
   

2. Run NoEntropy again:

   • A new cache will be created automatically
   • Files will be analyzed fresh via API

3. Prevent corruption:

   • Don't manually edit cache file
   • Let NoEntropy manage cache automatically

---

"Cache not working" or "Too many API calls"

Problem: Cache doesn't seem to reduce API calls.

Diagnosis:

Check if files are being modified:

ls -lt /path/to/Downloads | head

Reasons cache might not work:

1. Files are constantly changing:

   • If file modification time or size changes, cache is invalidated
   • This is expected behavior

2. Cache expired:

   • Cache entries older than 7 days are removed
   • Run organization more frequently

3. Cache deleted:

   • Check if .noentropy_cache.json exists in project root
   • If not, cache will rebuild on next run

Solution: This is often expected behavior, not a bug.

---

Undo Issues

"No completed moves to undo"

Problem: Cannot undo because no undo history exists.

Reasons:

1. No files have been organized yet

   • Run organization first

2. All moves already undone

   • You've already undone the previous organization

3. Undo log was deleted

   • Check if ~/.config/noentropy/data/undo_log.json exists

4. Undo log expired

   • Entries older than 30 days are automatically removed

Solution: Run organization to create new undo history.

---

"Undo log not found"

Problem: The undo log file doesn't exist.

Solutions:

1. Create data directory:

   mkdir -p ~/.config/noentropy/data
   

2. Run organization:

   • This will create the undo log automatically

---

"Skipping [file] - source already exists"

Problem: During undo, a file already exists at the original location.

This is a safety feature:

• NoEntropy won't overwrite existing files
• Prevents data loss

Solutions:

1. Manual inspection:

   • Check both source and destination files
   • Determine which one to keep
   • Manually resolve the conflict

2. Rename existing file:

   • Move or rename the file at source location
   • Run undo again

---

"Failed to restore [file]"

Problem: Unable to move file back to original location during undo.

Common causes:

1. Permission issues: See "Permission denied" section above
2. File deleted: Destination file was deleted after organization
3. Disk space: Not enough space at source location

Solution: Check logs for specific error, then address the underlying cause.

---

Build and Development Issues

"Rust not installed" or "cargo command not found"

Problem: Rust toolchain is not installed.

Solution:

Install Rust from official source:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then restart your terminal and try again.

---

Build errors or compilation failures

Problem: Cannot build from source.

Solutions:

1. Update Rust toolchain:

   rustup update
   

2. Clean build directory:

   cargo clean
   cargo build --release
   

3. Check Rust version:

   rustc --version
   

   • Ensure you have Rust 2024 edition or later

4. Check dependencies:

   cargo update
   

---

Platform-Specific Issues

Linux/macOS: "Permission denied" when running binary

Solution:

chmod +x noentropy

---

Windows: "Windows protected your PC" warning

This is expected for unsigned binaries.

Solution:

1. Click "More info"
2. Click "Run anyway"

Alternatively, build from source to avoid this warning.

---

macOS: "noentropy cannot be opened because the developer cannot be verified"

Solution:

1. First method (Recommended):

   xattr -d com.apple.quarantine noentropy
   

2. Alternative method:

   • Right-click the binary
   • Select "Open"
   • Click "Open" in the dialog

---

Getting More Help

If you've tried the solutions above and still have issues:

1. Check GitHub Issues: https://github.com/glitchySid/noentropy/issues

   • Someone might have reported the same issue
   • Solutions might already be available

2. Create a new issue:

   • Describe the problem clearly
   • Include error messages
   • Mention your OS and NoEntropy version
   • Describe steps to reproduce

3. Join discussions:

   • Check GitHub Discussions for community help
   • Share your use case and ask questions

Debug Mode

For detailed error information, run with Rust backtrace:

RUST_BACKTRACE=1 ./noentropy

This provides detailed stack traces for debugging issues.

---

Back to Main README