Troubleshooting

This guide helps you resolve common issues with kasl.

Common Issues

Activity Monitoring

Problem: Monitoring not starting

Symptoms:

kasl watch fails to start
No work sessions detected
Error messages about permissions

Solutions:

Check permissions:

# Linux/macOS
ls -la ~/.local/share/lacodda/kasl/

# Windows
dir "%LOCALAPPDATA%\lacodda\kasl"

Run in foreground for debugging:
```
kasl watch --foreground
```

Check for existing processes:

# Linux/macOS
ps aux | grep kasl

# Windows
tasklist | findstr kasl

Stop existing processes:
```
kasl watch --stop
```

Problem: False activity detection

Symptoms:

Work sessions start unexpectedly
Pauses not detected properly
Inconsistent timing

Solutions:

Adjust configuration:

kasl init  # Reconfigure monitor settings

Increase thresholds:

{
  "monitor": {
    "activity_threshold": 60,    // Increase from 30
    "pause_threshold": 120,      // Increase from 60
    "min_pause_duration": 30     // Increase from 20
  }
}

Check for background processes:

# Linux/macOS
ps aux | grep -E "(mouse|keyboard|input)"

Database Issues

Problem: Database locked

Symptoms:

"database is locked" errors
Cannot access data
Application crashes

Solutions:

Stop all kasl processes:
```
kasl watch --stop
```

Check file permissions:

# Linux/macOS
ls -la ~/.local/share/lacodda/kasl/kasl.db

# Windows
dir "%LOCALAPPDATA%\lacodda\kasl\kasl.db"

Fix permissions:

# Linux/macOS
chmod 600 ~/.local/share/lacodda/kasl/kasl.db
chmod 700 ~/.local/share/lacodda/kasl/

Check for corruption:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "PRAGMA integrity_check;"

Problem: Migration failures

Symptoms:

"migration failed" errors
Database schema issues
Application won't start

Solutions:

Check migration status:
```
kasl migrations status
```
View migration history:
```
kasl migrations history
```

Backup and reset:

# Backup current database
cp ~/.local/share/lacodda/kasl/kasl.db kasl_backup.db

# Remove database (will be recreated)
rm ~/.local/share/lacodda/kasl/kasl.db

# Restart kasl
kasl watch

Configuration Issues

Problem: Configuration not found

Symptoms:

"configuration not found" errors
Default settings used
Cannot save configuration

Solutions:

Check configuration location:

# Linux/macOS
ls -la ~/.local/share/lacodda/kasl/config.json

# Windows
dir "%LOCALAPPDATA%\lacodda\kasl\config.json"

Recreate configuration:
```
kasl init
```

Create directory manually:

# Linux/macOS
mkdir -p ~/.local/share/lacodda/kasl

# Windows
mkdir "%LOCALAPPDATA%\lacodda\kasl"

Problem: Invalid configuration

Symptoms:

"invalid configuration" errors
Application crashes on startup
Settings not applied

Solutions:

Validate JSON syntax:

# Using Python
python -m json.tool ~/.local/share/lacodda/kasl/config.json

# Using jq
jq . ~/.local/share/lacodda/kasl/config.json

Reset configuration:
```
kasl init --delete
kasl init
```

Check for syntax errors:

# Common issues:
# - Missing commas
# - Extra commas
# - Unquoted strings
# - Invalid JSON types

API Integration Issues

Problem: Authentication failures

Symptoms:

"authentication failed" errors
Cannot connect to APIs
Session expired messages

Solutions:

Clear cached sessions:

# Remove session files
rm ~/.local/share/lacodda/kasl/.gitlab_session
rm ~/.local/share/lacodda/kasl/.jira_session
rm ~/.local/share/lacodda/kasl/.si_session

Reconfigure integration:
```
kasl init
```
Check credentials:
- Verify API tokens are valid
- Check username/password
- Confirm API URLs

Test connectivity:

# Test GitLab
curl -H "Authorization: Bearer YOUR_TOKEN" https://gitlab.com/api/v4/user

# Test Jira
curl -u "username:password" https://jira.company.com/rest/api/2/myself

Problem: Network connectivity

Symptoms:

"connection failed" errors
Timeout errors
Cannot reach APIs

Solutions:

Check network connectivity:

# Test basic connectivity
ping gitlab.com
ping jira.company.com

# Test HTTPS
curl -I https://gitlab.com

Check proxy settings:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Check firewall settings:
- Ensure outbound HTTPS (443) is allowed
- Check corporate firewall rules
- Verify VPN connection if required

Task Management Issues

Problem: Tasks not found

Symptoms:

Empty task lists
"task not found" errors
Tasks not saving

Solutions:

Check database:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM tasks;"

Verify task creation:

# Create test task
kasl task --name "Test task" --completeness 0

# List tasks
kasl task --show

Check for database issues:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "PRAGMA integrity_check;"

Problem: Tag issues

Symptoms:

Tags not saving
Tag associations lost
Tag filtering not working

Solutions:

Check tag tables:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM tags;"
sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM task_tags;"

Recreate tags:

kasl tag create --name "test" --color "red"
kasl tag list

Check foreign key constraints:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "PRAGMA foreign_keys = ON;"

Report Issues

Problem: Reports not generating

Symptoms:

Empty reports
Missing data
Report generation errors

Solutions:

Check workday data:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM workdays ORDER BY date DESC LIMIT 5;"

Check pause data:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM pauses ORDER BY start DESC LIMIT 5;"

Generate report manually:
```
kasl report --last
```

Problem: Report submission failures

Symptoms:

"report send failed" errors
Reports not reaching server
Authentication issues

Solutions:

Check API configuration:

# Verify SiServer configuration
cat ~/.local/share/lacodda/kasl/config.json | jq .si

Test API connectivity:

# Test SiServer connection
curl -X POST https://api.company.com/health

Check authentication:

# Clear session and retry
rm ~/.local/share/lacodda/kasl/.si_session
kasl report --send

Debug Mode

Enable Debug Logging

# Enable debug mode
RUST_LOG=kasl=debug kasl watch --foreground

# Enable trace logging
RUST_LOG=kasl=trace kasl watch --foreground

# Enable SQLite logging
RUST_LOG=kasl=debug kasl report

Debug Information

Debug mode shows:

Configuration loading
Database operations
API requests/responses
Error details
Performance metrics

Common Debug Commands

# Check configuration
RUST_LOG=kasl=debug kasl init

# Debug task operations
RUST_LOG=kasl=debug kasl task --show

# Debug report generation
RUST_LOG=kasl=debug kasl report

# Debug API operations
RUST_LOG=kasl=debug kasl task --find

Performance Issues

High CPU Usage

Symptoms:

High CPU usage
System slowdown
Battery drain

Solutions:

Increase poll interval:

{
  "monitor": {
    "poll_interval": 1000  // Increase from 500
  }
}

Check for multiple instances:
```
ps aux | grep kasl
kasl watch --stop
```

Profile performance:

# Linux
perf record --call-graph=dwarf ./target/release/kasl watch
perf report

High Memory Usage

Symptoms:

High memory consumption
Memory leaks
Application crashes

Solutions:

Check memory usage:

# Linux/macOS
ps aux | grep kasl

# Windows
tasklist | findstr kasl

Restart application:
```
kasl watch --stop
kasl watch
```

Check for memory leaks:

# Use valgrind (Linux)
valgrind --leak-check=full ./target/release/kasl watch

Platform-Specific Issues

Windows Issues

Problem: Autostart not working

Solutions:

Check Task Scheduler:
- Open Task Scheduler
- Look for kasl tasks
- Verify task is enabled

Check Registry:

reg query "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run" /v kasl

Run as Administrator:
```
kasl autostart enable
```

Problem: Permission denied

Solutions:

Run as Administrator:
- Right-click Command Prompt
- "Run as administrator"
Check file permissions:
```
icacls "%LOCALAPPDATA%\lacodda\kasl"
```

macOS Issues

Problem: Input monitoring permissions

Solutions:

Grant Accessibility permissions:
- System Preferences → Security & Privacy → Privacy → Accessibility
- Add kasl to the list
Grant Input Monitoring permissions:
- System Preferences → Security & Privacy → Privacy → Input Monitoring
- Add kasl to the list

Problem: Autostart not working

Solutions:

Check LaunchAgents:
```
ls -la ~/Library/LaunchAgents/
```

Load LaunchAgent manually:

launchctl load ~/Library/LaunchAgents/com.lacodda.kasl.plist

Linux Issues

Problem: Input device access

Solutions:

Check user groups:
```
groups $USER
```
Add user to input group:
```
sudo usermod -a -G input $USER
```
Check device permissions:
```
ls -la /dev/input/
```

Problem: systemd service issues

Solutions:

Check service status:
```
systemctl --user status kasl
```

Enable service:

systemctl --user enable kasl
systemctl --user start kasl

Getting Help

Before Asking for Help

Check this guide for your specific issue
Enable debug logging and check output
Try the solutions provided above
Gather information about your system

Information to Provide

When reporting issues, include:

Operating system and version
kasl version (kasl --version)
Error messages (with debug logging)
Steps to reproduce
System configuration

Support Channels

GitHub Issues: https://github.com/lacodda/kasl/issues
Email: lahtachev@gmail.com
Documentation: https://kasl.lacodda.com

Keyboard shortcuts

kasl documentation