Troubleshooting Guide

This guide helps you diagnose and fix common issues with Refocus Shell.

Exit Codes

Refocus Shell uses standardized exit codes to help with script integration and error diagnosis:

Exit Code	Meaning	Common Causes
`0`	Success	Command completed successfully
`1`	General Error	Unspecified error, session not found, etc.
`2`	Invalid Arguments	Missing required arguments, invalid format, etc.
`3`	Database Error	Database connection failed, SQL errors, etc.
`4`	Permission Error	Insufficient file permissions, etc.
`5`	File System Error	File not found, disk space issues, etc.
`6`	Configuration Error	Invalid config, missing config files, etc.
`7`	State Error	Invalid application state (already active, disabled, etc.)

Using Exit Codes in Scripts

#!/bin/bash
focus on "my-project"
case $? in
    0) echo "Focus started successfully" ;;
    2) echo "Invalid arguments - check usage" ;;
    7) echo "Focus already active or disabled" ;;
    *) echo "Unexpected error occurred" ;;
esac

Common Exit Code Examples

# Success
focus on "coding"          # Exit code: 0

# Invalid arguments
focus on                   # Exit code: 2 (missing project)
focus past add             # Exit code: 2 (missing arguments)

# State errors
focus off                  # Exit code: 7 (no active session)
focus on "test"            # Exit code: 7 (already active)

# General errors
focus past delete 999      # Exit code: 1 (session not found)

Installation Issues

Command Not Found

Symptoms

$ focus on "test"
bash: focus: command not found

Diagnosis

# Check if focus is installed
which focus
ls -la ~/.local/refocus/

# Check shell integration
type focus
grep -r "refocus" ~/.bashrc ~/.profile

Solutions

Option 1: Reinstall

cd refocus-shell
./setup.sh install
source ~/.bashrc

Option 2: Manual shell integration

echo 'source ~/.local/refocus/lib/focus-function.sh' >> ~/.bashrc
source ~/.bashrc

Option 3: Check PATH

# If using manual installation
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

Dependencies Missing

Symptoms

$ focus on "test"  
./focus: line 25: sqlite3: command not found

Solutions

# Debian/Ubuntu
sudo apt-get install sqlite3 libnotify-bin jq

# Arch/Manjaro  
sudo pacman -S sqlite libnotify jq

# Fedora/RHEL
sudo dnf install sqlite libnotify jq

# openSUSE
sudo zypper install sqlite3 libnotify-tools jq

Permission Errors

Symptoms

$ focus on "test"
mkdir: cannot create directory '/home/user/.local/refocus': Permission denied

Solutions

# Fix directory permissions
sudo chown -R $USER:$USER ~/.local
chmod 755 ~/.local

# Create directories manually
mkdir -p ~/.local/refocus
chmod 755 ~/.local/refocus

Database Issues

Database Not Found

Symptoms

$ focus status
❌ Database not found: /home/user/.local/refocus/refocus.db

Diagnosis

# Check database file
ls -la ~/.local/refocus/refocus.db

# Check directory
ls -la ~/.local/refocus/

# Check environment variable
echo $REFOCUS_DB

Solutions

Initialize new database:

focus init

Restore from backup:

# Check for automatic backups
ls ~/.local/refocus/refocus.db.backup.*

# Restore latest backup
cp ~/.local/refocus/refocus.db.backup.* ~/.local/refocus/refocus.db

Import from export:

focus import backup.json

Database Corruption

Symptoms

$ focus status
Error: database disk image is malformed

Diagnosis

# Check database integrity
sqlite3 ~/.local/refocus/refocus.db "PRAGMA integrity_check;"

# Check file permissions
ls -la ~/.local/refocus/refocus.db

# Check disk space
df -h ~/.local/refocus/

Solutions

Option 1: Restore from backup

ls ~/.local/refocus/refocus.db.backup.*
cp ~/.local/refocus/refocus.db.backup.20250926_143022 ~/.local/refocus/refocus.db

Option 2: Recover data

# Try to dump recoverable data
sqlite3 ~/.local/refocus/refocus.db ".dump" > recovered_data.sql

# Create new database
rm ~/.local/refocus/refocus.db
focus init

# Import recovered data
sqlite3 ~/.local/refocus/refocus.db < recovered_data.sql

Option 3: Nuclear option (loses all data)

focus reset

Migration Errors

Symptoms

$ focus on "test"
Error: in prepare, no such table: sessions

Solutions

# Force migration
focus init

# Or reset and restore
focus export backup  # If possible
focus reset
focus import backup.json

Notification Issues

Nudges Not Appearing

Symptoms

No desktop notifications during focus sessions
No idle reminders when not focusing

Diagnosis

# Check nudge status
focus nudge status

# Test notification system
focus nudge test

# Check if notifications are enabled
notify-send "Test" "This should appear"

# Check desktop environment
echo $XDG_CURRENT_DESKTOP
echo $DISPLAY
echo $WAYLAND_DISPLAY

Solutions

Enable nudges:

focus nudge enable

Fix notification dependencies:

# Install notification tools
sudo apt-get install libnotify-bin

# Test manual notification
notify-send "Test" "Manual test"

Check cron jobs:

# View active cron jobs
crontab -l

# Look for refocus entries
crontab -l | grep focus-nudge

Debug cron environment:

# Enable verbose logging
export REFOCUS_VERBOSE=true

# Check logs
journalctl -f | grep focus-nudge
tail -f /var/log/syslog | grep focus-nudge

Wall Messages Instead of Desktop Notifications

Symptoms

Broadcast message from user@host (Thu Sep 26 14:20:02 2025):
FOCUS NUDGE: Focus Reminder - You're focusing on: project (10m elapsed)

Cause

Desktop notifications are failing, falling back to wall command.

Solutions

Fix display environment for cron:

# Check current environment
env | grep -E "(DISPLAY|WAYLAND|DBUS)"

# The installer should handle this automatically
./setup.sh install

Manual cron environment fix:

# Edit crontab
crontab -e

# Ensure the entry includes environment variables:
DISPLAY=:0
WAYLAND_DISPLAY=wayland-0
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
*/10 * * * * /home/user/.local/refocus/focus-nudge

Duplicate Notifications

Symptoms

Both desktop notifications AND wall messages
Multiple notifications for the same event

Solutions

# Check for multiple cron entries
crontab -l | grep focus-nudge

# Remove duplicate entries
crontab -e  # Remove extra lines

# Check for background processes
ps aux | grep focus-nudge

Prompt Issues

Prompt Not Updating

Symptoms

⏳ [project] doesn't appear in prompt
Prompt shows wrong project
Prompt doesn't clear after focus off

Diagnosis

# Check shell function
type focus
type focus-update-prompt

# Check original prompt backup
echo $REFOCUS_ORIGINAL_PS1

# Check current prompt
echo $PS1

Solutions

Manual prompt update:

focus-update-prompt

Reinstall shell integration:

./setup.sh install
source ~/.bashrc

Manual prompt restoration:

focus-restore-prompt
export PS1="$REFOCUS_ORIGINAL_PS1"

Prompt Appears in Wrong Terminals

Symptoms

Prompt shows in terminals where focus wasn't started
Inconsistent prompt across terminals

Explanation

This is normal behavior - the prompt indicator works across all terminals to show your current focus state.

Disable if unwanted

# Remove prompt integration
export REFOCUS_PROMPT_FORMAT=""

# Or disable via configuration
focus config set PROMPT_FORMAT ""

Session Issues

Can't Start Session

Symptoms

$ focus on "project"
❌ Cannot start new focus session while one is paused.

Solutions

# Check current status
focus status

# Handle paused session
focus continue  # Resume paused session
# OR
focus off      # Complete paused session

Lost Session Data

Symptoms

Sessions missing from focus past list
Incorrect session times
Missing notes

Diagnosis

# Check recent sessions
focus past list 20
focus past list -n 50  # Alternative flag format

# Check database directly
sqlite3 ~/.local/refocus/refocus.db "SELECT * FROM sessions ORDER BY id DESC LIMIT 10;"

# Check for data corruption
sqlite3 ~/.local/refocus/refocus.db "PRAGMA integrity_check;"

Solutions

# Restore from backup
focus import backup.json

# Or check automatic backups
ls ~/.local/refocus/refocus.db.backup.*
cp ~/.local/refocus/refocus.db.backup.* ~/.local/refocus/refocus.db

Time Calculation Errors

Symptoms

Negative session durations
Impossibly long sessions
Wrong elapsed time in nudges

Diagnosis

# Check system time
date

# Check session data
focus past list 5
focus past list -n 10  # Alternative flag format

# Check for invalid sessions
sqlite3 ~/.local/refocus/refocus.db "SELECT * FROM sessions WHERE duration_seconds < 0 OR duration_seconds > 86400;"

Solutions

# Fix system time
sudo ntpdate -s time.nist.gov

# Delete invalid sessions
focus past delete <session_id>

# Or modify session times
focus past modify <session_id> "project" "14:00" "16:00"

Performance Issues

Slow Commands

Symptoms

focus status takes several seconds
focus past list is very slow
Reports take a long time to generate

Diagnosis

# Check database size
ls -lh ~/.local/refocus/refocus.db

# Count sessions
sqlite3 ~/.local/refocus/refocus.db "SELECT COUNT(*) FROM sessions;"

# Check for database issues
sqlite3 ~/.local/refocus/refocus.db "PRAGMA integrity_check;"

Solutions

# Optimize database
sqlite3 ~/.local/refocus/refocus.db "VACUUM;"
sqlite3 ~/.local/refocus/refocus.db "ANALYZE;"

# Clean up old sessions
focus past list 100
focus past list -n 200  # Alternative flag format
# Delete very old sessions manually:
focus past delete <old_session_id>

High Memory Usage

Symptoms

High memory usage during report generation
System becomes slow when using Refocus Shell

Solutions

# Generate smaller reports
focus report custom 7   # Instead of custom 365

# Use database queries for large datasets
sqlite3 ~/.local/refocus/refocus.db "SELECT project, COUNT(*) FROM sessions GROUP BY project;"

Debug Mode

Enable Debug Output

# Enable verbose output
export REFOCUS_VERBOSE=true

# Run commands with debug info
focus on "debug-test"
focus status
focus off

Debug Information

Verbose mode shows:

Database queries being executed
File operations
Cron job management
Notification attempts
Prompt updates

Log Analysis

System Logs

# Check system logs for refocus entries
journalctl -u cron | grep focus-nudge
tail -f /var/log/syslog | grep focus

# Check user logs
journalctl --user | grep focus

Application Logs

# Enable logging to file
export REFOCUS_LOG_FILE="$HOME/.local/refocus/debug.log"

# Run commands and check log
focus on "test"
cat ~/.local/refocus/debug.log

Recovery Procedures

Complete Reinstall

# Backup data first
focus export emergency-backup

# Uninstall completely
./setup.sh uninstall
rm -rf ~/.local/refocus
rm -rf ~/.config/refocus-shell

# Clean shell configuration
grep -v "refocus" ~/.bashrc > ~/.bashrc.new
mv ~/.bashrc.new ~/.bashrc

# Reinstall
./setup.sh install
source ~/.bashrc

# Restore data
focus import emergency-backup.json

Emergency Data Recovery

From Automatic Backups

# Find backup files
find ~/.local/refocus -name "*.backup.*"

# Restore most recent
cp ~/.local/refocus/refocus.db.backup.* ~/.local/refocus/refocus.db

From Export Files

# Find export files
find ~ -name "refocus-export-*.json" -o -name "refocus-export-*.sql"

# Import most recent
focus import ~/path/to/export.json

From Git History (if versioned)

# If you've been versioning exports
cd ~/refocus-backups
git log --oneline
git checkout <commit> -- refocus-data.json
focus import refocus-data.json

Getting Help

Information Gathering

Before seeking help, gather this information:

# System information
uname -a
echo $SHELL
echo $XDG_CURRENT_DESKTOP

# Refocus Shell version and status
focus help
focus status
focus config show

# Installation details
ls -la ~/.local/refocus/
ls -la ~/.local/bin/focus

# Error reproduction
export REFOCUS_VERBOSE=true
# Run the problematic command

Common Solutions Summary

Installation issues: Reinstall with ./setup.sh install
Database issues: focus init or restore from backup
Notification issues: Check dependencies and cron jobs
Prompt issues: focus-update-prompt or reinstall
Performance issues: Database optimization with VACUUM
Data loss: Restore from automatic backups or exports

When All Else Fails

# Nuclear option - complete reset (LOSES ALL DATA)
focus reset

# Start fresh
focus init
focus on "recovery-test"
focus status

Next: Advanced Usage

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

Exit Codes

Using Exit Codes in Scripts

Common Exit Code Examples

Installation Issues

Command Not Found

Symptoms

Diagnosis

Solutions

Dependencies Missing

Symptoms

Solutions

Permission Errors

Symptoms

Solutions

Database Issues

Database Not Found

Symptoms

Diagnosis

Solutions

Database Corruption

Symptoms

Diagnosis

Solutions

Migration Errors

Symptoms

Solutions

Notification Issues

Nudges Not Appearing

Symptoms

Diagnosis

Solutions

Wall Messages Instead of Desktop Notifications

Symptoms

Cause

Solutions

Duplicate Notifications

Symptoms

Solutions

Prompt Issues

Prompt Not Updating

Symptoms

Diagnosis

Solutions

Prompt Appears in Wrong Terminals

Symptoms

Explanation

Disable if unwanted

Session Issues

Can't Start Session

Symptoms

Solutions

Lost Session Data

Symptoms

Diagnosis

Solutions

Time Calculation Errors

Symptoms

Diagnosis

Solutions

Performance Issues

Slow Commands

Symptoms

Diagnosis

Solutions

High Memory Usage

Symptoms

Solutions

Debug Mode

Enable Debug Output

Debug Information

Log Analysis

System Logs

Application Logs