Troubleshooting

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

Quick Diagnostic Checklist

Before diving into specific issues, check these common causes:

TypeSteps has Accessibility permissions enabled in System Settings
The app isn’t paused (menu bar icon shows keyboard, not keyboard.badge.ellipsis)
You’ve completed the onboarding flow
TypeSteps is the latest version
macOS is up to date

Tracking Issues

App Not Tracking Keystrokes

Permissions Not Granted

Symptom: Keystroke count stays at 0 even when typingSolution:

Open System Settings > Privacy & Security > Accessibility
Verify TypeSteps is in the list and toggled ON
If not in list, click + to manually add TypeSteps from Applications
Restart TypeSteps after enabling permissions

See the Permissions Guide for detailed steps.

Tracking is Paused

Symptom: Counts stopped increasing, menu bar shows keyboard with badge iconSolution:

Click the TypeSteps menu bar icon
Click Resume Tracking (or press Cmd+Shift+P)
Verify the icon changes back to regular keyboard symbol

From TypeStepsApp.swift:62-64:

Button(listener.isPaused ? "Resume Tracking" : "Pause Tracking") {
    listener.isPaused.toggle()
}

Event Monitor Not Started

Symptom: App shows permissions granted but still not trackingCause: The keystroke listener didn’t start after onboardingSolution:

Quit TypeSteps completely (Cmd+Q from menu bar)
Relaunch the app
The listener should auto-start if permissions are valid (TypeStepsApp.swift:21-23):

if KeystrokeListener.shared.checkPermissionsSilently() {
    KeystrokeListener.shared.startListening()
}

Onboarding Not Completed

Symptom: App keeps showing welcome screenSolution:

Complete the onboarding flow fully
Grant Accessibility permissions when prompted
Check that has_completed_onboarding is set:

UserDefaults.standard.bool(forKey: "has_completed_onboarding")

If stuck, reset onboarding:

defaults delete com.falakgala.typesteps has_completed_onboarding

Then restart TypeSteps.

Tracking Only Some Apps

App-Specific Tracking Issues

Symptom: Keystrokes counted in some apps but not othersPossible causes:

Sandboxed apps: Some apps with strict sandboxing may block event monitoring
Secure input: Apps like password managers enable secure input mode
Virtual machines: Keystrokes in VMs may not be captured

Solution:

For secure input apps: This is by design for security
For VMs: TypeSteps only tracks host Mac keystrokes
For other apps: Ensure they’re not requiring elevated privileges

Inaccurate Counts

Counts Too High or Too Low

Counts too high:

Holding down keys (key repeat) is counted
Multiple keyboards connected
Accessibility shortcuts triggering

Counts too low:

Some keystrokes filtered out (KeystrokeListener.swift:54-61):

for char in characters {
    if char.isLetter || char.isNumber || char.isPunctuation || char.isWhitespace {
        // Only these characters are counted
    }
}

Function keys, modifiers (Cmd, Option, etc.), and special keys are not counted.

Permission Issues

Permission Prompt Not Appearing

System Dialog Won't Show

Solution:

Open System Settings > Privacy & Security > Accessibility
Remove TypeSteps from the list if present
Restart your Mac
Launch TypeSteps - the prompt should now appear

If still not working:

# Reset accessibility permissions database (macOS Monterey+)
tccutil reset Accessibility

Then restart and try again.

Permission Granted But Not Working

Checkbox Enabled But No Tracking

Try these steps in order:

Toggle permission off and on:
- System Settings > Accessibility
- Turn TypeSteps OFF
- Turn TypeSteps ON
- Restart TypeSteps
Re-add the app:
- Remove TypeSteps from Accessibility list
- Click + button
- Add TypeSteps.app from Applications
- Enable it
Check for multiple installations:
- Search for duplicate TypeSteps in /Applications
- Remove all copies
- Reinstall from single source
Verify correct app version:
- Ensure the one in Accessibility matches the one you’re running
- Check bundle identifier matches

Permission Revoked After Update

Lost Permissions After macOS Update

Common issue: macOS updates sometimes reset app permissionsSolution:

Open System Settings > Accessibility
TypeSteps should still be in the list
Toggle it OFF then ON again
If not in list, re-add it
Restart TypeSteps

This is a known macOS behavior - consider exporting your data before major OS updates.

Data & Statistics Issues

Stats Not Showing in Dashboard

Dashboard Shows Zero Everywhere

Possible causes:

Fresh install: No data collected yet
- Start typing and wait a few seconds
- Stats should appear immediately
Data corruption:
- Check Console.app for errors
- Try exporting data (tests if data exists)
- If export works, data is intact
UserDefaults cleared:
- Data may have been reset
- Check if you have a backup to import
Different user account:
- TypeSteps data is per-macOS-user
- Verify you’re in the correct account

Historical Data Missing

Symptom: Today’s data shows, but past days are emptyCheck:

Export your data and examine the JSON
Look for dailyStats entries with past dates
If empty, data was likely reset or never collected

Solution:

If you have a backup, import it
Otherwise, data cannot be recovered
Set up regular backups going forward

Numbers Don't Match

Usually caused by:

Caching/refresh delay
UI not updating in real-time

Solution:

Close and reopen the dashboard window
Click menu bar to refresh
Quit and restart TypeSteps if issue persists

The menu bar and dashboard pull from the same data source (StorageManager.swift:104):

func getCount(for date: Date = Date()) -> Int { 
    return dailyStats[dateFormatter.string(from: date)] ?? 0 
}

WakaTime Integration Issues

WakaTime Data Not Showing

No WakaTime Stats in Dashboard

Check these steps:

API Key configured:
- Settings > WakaTime API Key field is filled
- Key is correct (test at wakatime.com)
WakaTime has data for today:
- Visit wakatime.com/dashboard
- Verify you’ve coded today
- Wait for WakaTime to process (can take 5-15 minutes)
Network connectivity:
- Ensure your Mac can reach wakatime.com
- Check firewall settings
Fetch error:
- WakaTimeManager shows lastError if fetch fails
- Check Console.app for “WakaTime Fetch Error”

Authentication Failed Error

Error message: “WakaTime Fetch Error: Authentication failed”Cause: Invalid API keySolution:

Go to wakatime.com > Settings > Account
Copy your secret API key (not the public one)
Paste into TypeSteps settings
Ensure no extra spaces or characters

The API uses Base64 encoding (WakaTimeManager.swift:16-18):

let credentialData = apiKey.data(using: .utf8)!
let base64Credentials = credentialData.base64EncodedString()

Zero Minutes Despite Coding

Symptom: WakaTime connected but shows 0 minutesReasons:

No coding today yet: WakaTime only shows today’s data
WakaTime not installed in editors: Install WakaTime plugins
Time zone differences: WakaTime “today” may be different timezone
WakaTime sync delay: Wait 15 minutes after coding

Debug:

Manually check WakaTime API:

curl -H "Authorization: Basic $(echo -n YOUR_API_KEY | base64)" \
  "https://wakatime.com/api/v1/users/current/summaries?start=$(date +%Y-%m-%d)&end=$(date +%Y-%m-%d)"

Goal & Notification Issues

Goal Notifications Not Appearing

Reached Goal But No Notification

Check:

Notification permissions:
- System Settings > Notifications > TypeSteps
- Ensure “Allow Notifications” is ON
Already notified today:
- TypeSteps only notifies once per milestone per day
- Check notifiedMilestones in exported data
Goal not set:
- Verify daily goal is configured (not 0)
- Settings > Daily Goal
Do Not Disturb:
- macOS Focus modes may block notifications
- Check Focus settings

Multiple Notifications for Same Goal

Should not happen: TypeSteps tracks notified milestonesIf it does:

Export your data
Check notifiedMilestones structure
May indicate data saving issue
Restart app to clear state

App Performance Issues

High CPU Usage

TypeSteps Using Too Much CPU

Normal behavior:

TypeSteps monitors global keyboard events
Should use less than 1% CPU when idle
Brief spikes when typing are normal

If consistently high:

Check Activity Monitor for exact usage
Quit and restart TypeSteps
Remove and re-grant Accessibility permissions
Check for macOS or TypeSteps updates

Performance optimization:

Minute stats are pruned to 120 entries (StorageManager.swift:70-73)
Events are handled on main thread efficiently

App Won’t Launch

TypeSteps Crashes on Startup

Troubleshooting steps:

Check crash logs:
- Open Console.app
- Search for TypeSteps crashes
- Look for error messages

Reset preferences:

# Backup first
defaults export com.falakgala.typesteps ~/typesteps-prefs.plist

# Reset
defaults delete com.falakgala.typesteps

Reinstall app:
- Delete TypeSteps from Applications
- Empty Trash
- Download and reinstall fresh copy
Check macOS compatibility:
- Verify TypeSteps supports your macOS version
- Update macOS if needed

Data Export/Import Issues

Export Fails or Creates Empty File

Can't Export Data

Possible causes:

No data to export:
- Start typing to generate some statistics
- Check dashboard shows non-zero counts
File permissions:
- Try saving to Desktop instead
- Check folder write permissions
Encoding error:
- Check Console.app for JSON encoding errors
- May indicate corrupt data structure

Verify data exists:

StorageManager.shared.getTotalAllTime() // Should be > 0

Import Fails with Error

Cannot Import Backup File

Error handling (StorageManager.swift:345-347):

guard let backup = try? JSONDecoder().decode(BackupData.self, from: data) else { 
    return false 
}

Common reasons:

Invalid JSON:
- File corrupted during transfer
- Manually edited incorrectly
- Wrong file selected Fix: Validate JSON at jsonlint.com
Version mismatch:
- Backup from newer TypeSteps version
- Missing required fields Fix: Ensure same or compatible version
File encoding:
- Opened and saved in wrong text editor
- UTF-8 encoding required Fix: Use original export file, don’t edit

Getting More Help

Diagnostic Information to Collect

Before reporting issues, gather:

macOS version: System Settings > About
TypeSteps version: About TypeSteps menu
Console logs:
- Open Console.app
- Filter for “TypeSteps”
- Copy relevant error messages
Accessibility status:
- System Settings > Accessibility > TypeSteps status
Expected vs actual behavior

Debug Mode

Check Console.app while running TypeSteps to see debug output:

“WakaTime Fetch Error: …”
Permission check results
Data save/load operations

Filter by “TypeSteps” or “keystroke” to find relevant logs.

Reset to Factory State

Nuclear option: Complete reset of TypeSteps

# Export data first!
# Then:

# Remove all preferences
defaults delete com.falakgala.typesteps

# Remove from Accessibility
# (System Settings > Accessibility > remove TypeSteps)

# Delete app
rm -rf /Applications/TypeSteps.app

# Reinstall fresh

This removes all data, settings, and permissions. Only use if other solutions fail.

Prevention Tips

Regular Backups

Export your data monthly or after reaching milestones - see Data Management

Keep Updated

Update TypeSteps and macOS regularly for bug fixes

Monitor Permissions

Check Accessibility permissions after macOS updates

Test After Changes

After changing settings, verify tracking still works

Still Need Help?

If none of these solutions work:

Check for known issues: Visit the TypeSteps website or repository
Report bugs: Provide diagnostic info collected above
Community forums: Other users may have encountered similar issues

Most issues are related to permissions or onboarding. Double-check the Permissions Guide first.

Get Started

Core Features

Integrations

User Guide

Quick Diagnostic Checklist

Tracking Issues

App Not Tracking Keystrokes

Tracking Only Some Apps

Inaccurate Counts

Permission Issues

Permission Prompt Not Appearing

Permission Granted But Not Working

Permission Revoked After Update

Data & Statistics Issues

Stats Not Showing in Dashboard

Menu Bar Stats vs Dashboard Mismatch

WakaTime Integration Issues

WakaTime Data Not Showing

Goal & Notification Issues

Goal Notifications Not Appearing

App Performance Issues

High CPU Usage

App Won’t Launch

Data Export/Import Issues

Export Fails or Creates Empty File

Import Fails with Error

Getting More Help

Diagnostic Information to Collect

Debug Mode

Reset to Factory State

Prevention Tips

Still Need Help?

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

User Guide

Documentation Index

​Quick Diagnostic Checklist

​Tracking Issues

​App Not Tracking Keystrokes

​Tracking Only Some Apps

​Inaccurate Counts

​Permission Issues

​Permission Prompt Not Appearing

​Permission Granted But Not Working

​Permission Revoked After Update

​Data & Statistics Issues

​Stats Not Showing in Dashboard

​Menu Bar Stats vs Dashboard Mismatch

​WakaTime Integration Issues

​WakaTime Data Not Showing

​Goal & Notification Issues

​Goal Notifications Not Appearing

​App Performance Issues

​High CPU Usage

​App Won’t Launch

​Data Export/Import Issues

​Export Fails or Creates Empty File

​Import Fails with Error

​Getting More Help

​Diagnostic Information to Collect

​Debug Mode

​Reset to Factory State

​Prevention Tips

​Still Need Help?

Build docs developers (and LLMs) love

Quick Diagnostic Checklist

Tracking Issues

App Not Tracking Keystrokes

Tracking Only Some Apps

Inaccurate Counts

Permission Issues

Permission Prompt Not Appearing

Permission Granted But Not Working

Permission Revoked After Update

Data & Statistics Issues

Stats Not Showing in Dashboard

Menu Bar Stats vs Dashboard Mismatch

WakaTime Integration Issues

WakaTime Data Not Showing

Goal & Notification Issues

Goal Notifications Not Appearing

App Performance Issues

High CPU Usage

App Won’t Launch

Data Export/Import Issues

Export Fails or Creates Empty File

Import Fails with Error

Getting More Help

Diagnostic Information to Collect

Debug Mode

Reset to Factory State

Prevention Tips

Still Need Help?