Troubleshooting Worker

This guide covers common issues you might encounter with Worker and how to resolve them.

Connection Issues

Worker Shows Disconnected (Red Indicator)

Symptoms:

• Red pulsing dot in Aura's sidebar
• "Worker not connected" errors when using Digital Grid tools
• Operations fail with connection timeout

Solutions:

1. Check if Worker is running

   • Look for the Worker icon in your system tray (menu bar on macOS)
   • If not visible, launch Worker from your applications

2. Verify the port

   • Worker defaults to port 8000
   • Check that Aura's settings match Worker's port
   • Look for port conflicts with other applications

3. Check browser permissions

   • Your browser must allow localhost connections
   • Try disabling any browser extensions that block local network access
   • Some corporate security software may block localhost

4. Test directly in browser

   • Open http://127.0.0.1:8000/healthcheck in a new tab
   • You should see {"status": "ok"}
   • If this fails, Worker isn't accessible

5. Restart Worker

   • Click the Worker tray icon → Restart
   • Or quit and relaunch the application

Connection Works Intermittently

Symptoms:

• Worker connects sometimes but not others
• Connection drops during operations

Solutions:

1. Check system resources

   • Ensure you have enough RAM available
   • Close unnecessary applications

2. Firewall settings

   • Add Worker to firewall exceptions
   • Allow incoming connections on port 8000

3. Antivirus software

   • Some antivirus programs block local network connections
   • Add Worker to the allowed applications list

Version Compatibility Issues

Worker Shows "Update Required" (Orange Indicator)

Symptoms:

• Orange pulsing dot in Aura's sidebar
• "Update required" message
• Alert showing your version is incompatible

Solutions:

1. Download the latest Worker version

   • Visit the releases page
   • Download the appropriate version for your operating system

2. Install the update

   • Close the currently running Worker (right-click tray icon → Quit)
   • Install the new version (it replaces the old one)
   • Launch Worker again

3. Verify the update

   • Check the version in the system tray menu
   • Refresh Aura and confirm the status turns green

Version Check Fails

Symptoms:

• Worker connects but shows incompatible
• Version appears as "unknown"

Solutions:

1. Update Worker

   • Very old Worker versions may not have version reporting
   • Download the latest version to resolve this

2. Check network/firewall

   • Ensure the /version endpoint isn't being blocked

Working Directory Issues

"Directory not found" Error

Symptoms:

• Working directory validation fails
• Error message about path not existing

Solutions:

1. Verify the path exists

   • Open the path in your file manager
   • Create the directory if it doesn't exist

2. Check for typos

   • Ensure the path is spelled correctly
   • Pay attention to case sensitivity (important on Linux/macOS)

3. Use absolute paths

   • Always use full paths, not relative paths
   • Example: /Users/username/Documents/AuraData not ~/Documents/AuraData

"Permission denied" Error

Symptoms:

• Directory exists but Worker can't access it
• Read or write operations fail

Solutions:

1. Check file permissions

   # macOS/Linux
   ls -la /path/to/directory
   # Should show read/write for your user

2. Grant Full Disk Access (macOS)

   • System Preferences → Security & Privacy → Privacy → Full Disk Access
   • Add Worker to the list

3. Run as appropriate user

   • Ensure Worker runs as a user with permission to the directory
   • Avoid system-protected directories

Files Not Appearing

Symptoms:

• Files saved but not visible
• Export operations report success but no file created

Solutions:

1. Refresh the file browser

   • The file system view may be cached
   • Re-validate the working directory

2. Check subdirectories

   • Files may be saved in a subdirectory
   • Look for output/ or similar folders

3. Verify disk space

   • Ensure you have free space on the drive
   • Large point clouds need significant space

Processing Issues

Operations Take Too Long

Symptoms:

• Progress bar doesn't move
• Operations seem stuck

Solutions:

1. Check data size

   • Large point clouds take longer to process
   • Consider processing smaller subsets first

2. Monitor system resources

   • Check CPU and memory usage
   • Close other heavy applications

3. View Worker logs

   • Check Worker's console output for progress
   • Look for error messages or warnings

Operations Fail Midway

Symptoms:

• Processing starts but fails before completion
• Error messages in Aura

Solutions:

1. Check disk space

   • Temporary files can be large
   • Ensure adequate free space

2. Verify input files

   • Ensure source files are not corrupted
   • Check that files are in the expected format

3. Restart and retry

   • Restart Worker
   • Try the operation again

Out of Memory Errors

Symptoms:

• Worker crashes during processing
• "Memory allocation failed" errors

Solutions:

1. Close other applications

   • Free up system RAM

2. Process smaller areas

   • Use clipping to reduce data size
   • Process in batches

3. Increase system RAM

   • 16 GB recommended for large datasets
   • 32 GB for very large point clouds

Digital Grid Specific Issues

Poles Not Placing Correctly

Symptoms:

• Poles appear in wrong locations
• Height calculations seem off

Solutions:

1. Check point cloud alignment

   • Verify the coordinate system is correct
   • Check for vertical datum issues

2. Zoom in closer

   • More accurate placement at higher zoom levels
   • Click directly on the feature

Distance Calculations Fail

Symptoms:

• "Calculate Distances" doesn't complete
• No results returned

Solutions:

1. Verify Worker connection

   • Distance calculations require Worker

2. Check point cloud coverage

   • Ensure point cloud covers the analysis area
   • Verify classification includes relevant classes

Checking Worker Logs

For detailed troubleshooting, check Worker's logs:

Console Output

If running Worker from command line:

# Logs appear in the terminal
./Worker-app

System Tray Status

Click the Worker tray icon to see:

• Current version
• Port number
• Status (OK or error)

Getting Help

If you're still experiencing issues:

1. Note the error message - Exact text helps with diagnosis
2. Check Worker version - Ensure you have the latest version
3. Document steps to reproduce - What actions lead to the problem
4. Contact support - Provide details for assistance

Common Error Messages

Next Steps

After resolving issues:

1. Configure your working directory properly
2. Start using Digital Grid tools
3. Learn about analysis features