Troubleshooting Guide¶

This guide helps you diagnose and resolve common issues with SmrtHub.

Diagnostic Tools¶

Health Check Scripts¶

Run these scripts to quickly identify issues:

# Overall system health check
.\tools\Check-SystemHealth.ps1

# Component status verification
.\tools\Test-Components.ps1

# Network connectivity test
.\tools\Test-NetworkBridge.ps1

Log Analysis¶

Check logs for error patterns:

# View recent errors
Get-Content Logs\smrthub.log | Select-String "ERROR|CRITICAL" | Select-Object -Last 20

# Monitor real-time logs
Get-Content Logs\smrthub.log -Wait -Tail 10

# Component-specific logs
Get-Content Logs\SmrtHub.App.log
Get-Content Logs\clipboard.log
Get-Content Logs\python_core.log

Common Issues¶

Build and Setup Issues¶

".NET 8.0 SDK not found"¶

Symptoms: Build fails with framework errors

Solutions:

# Check installed .NET versions
dotnet --list-sdks

# Download and install .NET 8.0 SDK
# https://dotnet.microsoft.com/download/dotnet/8.0

# Verify installation
dotnet --version  # Should show 8.0.x

"Python virtual environment creation failed"¶

Symptoms: Python setup fails, import errors

Solutions:

# Check Python installation
python --version  # Should be 3.12+

# Manual virtual environment setup
cd PythonApp
python -m venv venv --clear
.\venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

# Test Python core import
python -c "import python_core; print('Success')"

"MSBuild errors during compilation"¶

Symptoms: C# projects fail to build

Solutions:

# Clean solution
dotnet clean SmrtHub.sln

# Restore NuGet packages
dotnet restore SmrtHub.sln

# Build with detailed output
dotnet build SmrtHub.sln --verbosity detailed

# Check specific project
cd CSApps\SmrtHub.App
dotnet build

Runtime Issues¶

"Components not starting"¶

Symptoms: SmrtHub.App starts but other components don't launch

Diagnostic:

# Check process status
Get-Process | Where-Object {$_.ProcessName -like "*SmrtHub*"}

# Manual component start
cd CSApps\ClipboardMonitor
dotnet run --configuration Debug

Solutions: 1. Check dependencies: Ensure all required .NET libraries are installed 2. Verify paths: Update paths in configuration files if needed 3. Run as administrator: Some components may need elevated privileges 4. Check Windows Defender: Add SmrtHub directory to exclusions

"HTTP Bridge connection refused"¶

Symptoms: C# components can't communicate with Python core

Diagnostic:

# Test bridge connectivity
curl http://localhost:5001/api/health/status
curl http://localhost:5000/api/status

# Check port usage
netstat -ano | findstr :5001
netstat -ano | findstr :5000

Solutions: 1. Start Python core manually:

cd PythonApp
.\venv\Scripts\activate
python -m python_core

Check firewall settings:

# Allow Python through Windows Firewall
New-NetFirewallRule -DisplayName "SmrtHub Python Core" -Direction Inbound -Protocol TCP -LocalPort 5001 -Action Allow

Kill conflicting processes:

# Find process using port 5001
netstat -ano | findstr :5001
# Kill the process (replace PID)
taskkill /PID <ProcessID> /F

"Clipboard monitoring not working"¶

Symptoms: Clipboard changes not detected

Diagnostic:

# Check ClipboardMonitor logs
Get-Content Logs\clipboard.log -Tail 20

# Test manual clipboard detection
# Copy some text and check logs immediately

Solutions: 1. Restart ClipboardMonitor:

cd CSApps\ClipboardMonitor
dotnet run --configuration Debug

Check Windows permissions: Some applications block clipboard access
Verify event hooks: ClipboardMonitor uses Win32 API hooks
Check antivirus interference: Whitelist SmrtHub executable

Performance Issues¶

"High CPU usage"¶

Symptoms: SmrtHub consuming excessive CPU resources

Diagnostic:

# Monitor resource usage
Get-Process | Where-Object {$_.ProcessName -like "*SmrtHub*"} | Select-Object Name, CPU, WorkingSet

Solutions: 1. Adjust heartbeat intervals:

{
  "language": "en",
  "enable_filesystem_watcher": false,
  "index_refresh": {
    "mode": "daily",
    "on_startup": true,
    "on_startup_only_if_exists": true,
    "daily_time": "03:00",
    "every_n_days": 1,
    "weekly_days": ["sun"],
    "idle_after": 30
  }
}

Optimize file indexing:

{
  "language": "en",
  "enable_filesystem_watcher": false,
  "index_refresh": {
    "mode": "weekly",
    "on_startup": false,
    "on_startup_only_if_exists": true,
    "daily_time": "03:00",
    "every_n_days": 7,
    "weekly_days": ["sun"],
    "idle_after": 60
  }
}

Enable content filtering:

{
  "excluded_app_names": ["pythonapp.exe", "code.exe"],
  "blacklisted_window_keywords": ["terminal", "developer"],
  "excluded_dirs": ["AppData"],
  "excluded_extensions": [".tmp", ".log"]
}

"High memory usage"¶

Symptoms: Memory consumption growing over time

Solutions: 1. Restart components daily:

# Add to Task Scheduler
.\tools\Restart-SmrtHubComponents.ps1

Clear logs regularly:

# Archive old logs
.\tools\Archive-Logs.ps1

Optimize cache settings:

# Limit cache sizes
CACHE_CONFIG = {
    "max_detection_cache": 100,
    "max_file_cache": 50
}

Network and Communication Issues¶

"Browser extension not connecting"¶

Symptoms: Browser extension shows "disconnected"

Diagnostic:

# Test web listener
curl http://localhost:5000/api/status

# Check browser console for errors

Solutions: 1. Verify web listener is running 2. Check browser extension manifest: Ensure permissions are correct 3. Update extension: Reload the extension in browser settings 4. Test with different browser: Isolate browser-specific issues

"File saving failures"¶

Symptoms: Content detected but not saved

Diagnostic:

# Check save worker logs
Get-Content Logs\smrthub.log | Select-String "save_worker"

# Test manual save
curl -X POST http://localhost:5001/api/save/test -H "Content-Type: application/json" -d '{"content":"test","filename":"test.txt"}'

Solutions: 1. Check directory permissions: Ensure write access to SmrtSpace directory 2. Verify disk space: Ensure sufficient storage available 3. Check path length: Windows has 260-character path limits 4. Review SmrtSpace configuration: Verify target directories exist

Advanced Troubleshooting¶

Debug Mode¶

Enable detailed logging for troubleshooting:

# Set environment variable
$env:SMRTHUB_DEBUG = "true"

Or set the Python Core log level in python_core/config/python-core-logging.json:

{
   "level": "DEBUG"
}

Component Isolation¶

Test components individually:

# Test Python core only
cd PythonApp
.\venv\Scripts\activate
python -m python_core --debug

# Test specific C# component
cd CSApps\ClipboardMonitor
dotnet run --configuration Debug

# Test HTTP bridge
curl -v http://localhost:5001/api/health/status

Network Debugging¶

Capture network traffic for API issues:

# Use netsh to trace HTTP traffic
netsh trace start capture=yes tracefile=smrthub_trace.etl provider=Microsoft-Windows-HttpService

# Reproduce the issue, then stop tracing
netsh trace stop

Performance Profiling¶

Profile component performance:

# Use dotnet diagnostic tools
dotnet-trace collect --process-id <PID> --duration 00:00:30

# Python profiling
cd PythonApp
.\venv\Scripts\activate
python -m cProfile -o profile.out -m python_core

Getting Help¶

Log Collection¶

When seeking help, collect these logs:

# Create support package
.\tools\Collect-SupportLogs.ps1

# This creates: smrthub-support-logs-YYYYMMDD.zip
# Include this file when reporting issues

Issue Reporting Template¶

Use this template when reporting issues:

## Issue Description
[Brief description of the problem]

## Environment
- Windows Version: [e.g., Windows 11 22H2]
- .NET Version: [from `dotnet --version`]
- Python Version: [from `python --version`]
- SmrtHub Version: [if available]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [Third step]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Logs
[Attach relevant log excerpts or support package]

## Additional Context
[Any other relevant information]

Community Resources¶

Documentation: This documentation site
Issue Tracker: GitHub Issues (if available)
Discussions: Community forums or Discord
Support: Direct email for critical issues