little-helper

Troubleshooting Guide - My Little Helper

Common Issues and Solutions

1. Compilation Errors

Issue: “javac is not recognized as an internal or external command”

Cause: Java JDK not installed or not in PATH

Solution:

  1. Download and install Java JDK:
    • Oracle JDK: https://www.oracle.com/java/technologies/downloads/
    • OpenJDK: https://adoptium.net/
  2. Add Java to PATH:
    • Search “Environment Variables” in Windows
    • Add Java bin folder to System PATH
    • Example: C:\Program Files\Java\jdk-17\bin
  3. Restart terminal and try again

Issue: “error: unmappable character for encoding”

Cause: File encoding issue

Solution:

javac -encoding UTF-8 *.java

The START.bat already includes this flag.

2. Runtime Errors

Issue: “java is not recognized as an internal or external command”

Cause: Java Runtime (JRE) not installed or not in PATH

Solution: Same as JDK installation above. JDK includes JRE.

Issue: App crashes immediately on startup

Cause: Multiple possible causes

Solution:

  1. Check Java version: java -version (need Java 8+)
  2. Recompile: Delete all .class files and recompile
  3. Check console for error messages
  4. Verify all .java files are present in src folder

3. Desktop Shortcut Issues

Issue: Desktop shortcut not created

Cause: PowerShell execution policy or permissions

Solution - Manual Creation:

  1. Right-click Desktop -> New -> Shortcut
  2. Target: cmd.exe
  3. Arguments: /c cd /d "C:\path\to\My Little Helper\src" && java Main
  4. Name: My Little Helper
  5. Change icon (optional): Browse to assets\my_little_helper.ico

Issue: Shortcut icon not showing

Cause: Icon file missing or path incorrect

Solution:

  1. Verify assets\my_little_helper.ico exists
  2. If missing, run: assets\create_icon.ps1
  3. Delete existing shortcut
  4. Restart app to recreate shortcut

Issue: Cannot pin to taskbar

Cause: Group Policy restriction (common in corporate environments)

Solution - Manual Pin:

  1. Right-click desktop shortcut
  2. Select “Pin to taskbar”
  3. If option missing, IT policy prevents it (no workaround)

4. Feature-Specific Issues

Email Header Analyzer

Issue: Export folder not created

Issue: Cannot parse headers

Issue: JSON export has encoding issues

Web Page Snapshot

Issue: “No supported browser found”

Issue: Snapshot is blank or black

Issue: Full page mode cuts off content

Webmail Portal Access

Issue: Browser opens but page doesn’t load

Issue: Wrong browser opens

5. Display Issues

Issue: Colors not showing / Strange characters

Cause: Terminal doesn’t support ANSI colors

Solution:

Note: App includes ASCII-safe fallback for text.

Issue: Text overlaps or wraps incorrectly

Cause: Terminal window too narrow

Solution:

6. Permission Issues

Issue: “Access denied” when creating files

Cause: Insufficient permissions on user folder

Solution:

  1. Run as regular user (not admin) - app designed for user permissions
  2. Check Documents folder permissions
  3. Antivirus may block - add exception

Issue: Browser cache clearing fails

Cause: Browser is open or files locked

Solution:

  1. Close browser completely
  2. End browser processes in Task Manager
  3. Try again

7. Performance Issues

Issue: App runs slowly

Cause: Large browser cache or system resources

Solution:

Issue: Snapshot takes very long

Cause: Complex page or slow internet

Solution:

8. Update and Compatibility

Issue: Features not working after Windows update

Cause: Windows update changed paths or settings

Solution:

  1. Recompile app: javac -encoding UTF-8 *.java
  2. Check browser installation paths
  3. Verify Java version still compatible

Issue: Works on one PC but not another

Cause: Different configurations

Solution - Check:

Getting Help

Before Asking for Help

Collect this information:

  1. Windows version: winver
  2. Java version: java -version
  3. Error message (exact text)
  4. Steps to reproduce
  5. What you’ve already tried

Support Channels

  1. Check README.md - May already have answer
  2. Review FEATURES.md - Understand what feature should do
  3. Check GitHub Issues - Someone may have same problem
  4. Create New Issue - Provide collected information above

Reporting Bugs

Include:

Advanced Troubleshooting

Clean Reinstall

  1. Backup any reports/snapshots you want to keep
  2. Delete project folder
  3. Re-extract/re-clone fresh copy
  4. Compile and test

Verify Java Installation

java -version
javac -version

Both should work and show similar versions.

Verify File Integrity

Check that all files are present:

cd "C:\path\to\My Little Helper"
Get-ChildItem -Recurse -File | Select-Object FullName

Compare with project structure in README.

Enable Debug Mode

To see more detailed errors:

  1. Edit Main.java
  2. Look for try-catch blocks
  3. Change e.getMessage() to e.printStackTrace()
  4. Recompile
  5. Run and copy full error output

Known Limitations

By Design

  1. Browser Detection: Checks standard installation paths only
  2. Snapshot Feature: Requires Chrome or Edge
  3. Shortcut Creation: Requires PowerShell
  4. Network Features: Require internet connection

Platform Specific

  1. Windows Only: Not compatible with Mac/Linux
  2. Windows 10/11: Best on Windows 11, works on Windows 10
  3. Java 8+: Older Java versions not supported

Security Restrictions

  1. Corporate Policies: Some features may be blocked by IT
  2. Antivirus: May flag PowerShell scripts (false positive)
  3. UAC: Does not request admin (runs as user)

Emergency Recovery

If App Won’t Start At All

  1. Delete all .class files: 
    cd src
Remove-Item *.class
  2. Recompile everything: 
    javac -encoding UTF-8 *.java
  3. Test minimal startup: 
    echo "11" | java Main
  4. If still failing, check Java: 
    java -version
javac -version
  5. Last resort - fresh install:
    • Download fresh copy
    • Delete old folder
    • Start from scratch

FAQ

Q: Do I need admin rights? A: No. App runs with regular user permissions.

Q: Is internet required? A: Only for webmail portals and web snapshots. All help content is offline.

Q: Can I use on Windows 10? A: Yes, most features work. Designed for Windows 11 but backwards compatible.

Q: Does it collect my data? A: No. Everything runs locally. No telemetry or network calls except when you explicitly open URLs.

Q: Can I modify the code? A: Yes! It’s open source. Edit, recompile, use as you wish.

Q: Why won’t my antivirus let it run? A: False positive. App uses PowerShell which some AV flags. Review code and add exception.

Still having issues? Create a GitHub issue with full details!