Skip to main content
Having trouble with Track Better? This guide covers the most common issues and how to resolve them.

​
App Not Loading

If the app fails to load or shows a blank screen:

​
Check Browser Compatibility

Track Better works best on modern browsers:
  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+

​
Clear Browser Cache

  1. Open your browser settings
  2. Navigate to Privacy or Clear browsing data
  3. Select Cached images and files
  4. Clear the cache for the last 24 hours
  5. Reload Track Better

​
Service Worker Issues

If the app was working but suddenly stopped:
  1. Open browser DevTools (F12)
  2. Go to Application > Service Workers
  3. Click Unregister next to the Track Better service worker
  4. Refresh the page
The service worker will automatically re-register and the app should load normally.

​
Data Not Saving

​
Check LocalStorage Availability

Track Better uses browser localStorage to save your data. If data isn’t persisting:
  1. Ensure you’re not in Private/Incognito mode (localStorage is restricted)
  2. Check that cookies and site data are not blocked for this domain
  3. Verify localStorage is enabled in browser settings

​
Storage Quota Exceeded

If you see errors about storage being full: 
QuotaExceededError: Failed to execute 'setItem' on 'Storage'
Solution:
  1. Go to Settings tab in Track Better
  2. Export your data to create a backup
  3. Use Hard Reset All Data to clear old data
  4. Import your data to restore recent progress
See Data Management for more details on managing localStorage.

​
Verify Data is Saving

  1. Open browser DevTools (F12)
  2. Go to Application > Local Storage
  3. Look for entries like completedExercises, userName, activeTab
  4. If these are present, data is saving correctly

​
Videos Not Playing

Exercise demonstration videos may fail to load for several reasons:

​
Network Connection

Videos require an internet connection to load (they’re not cached locally).
  1. Check your internet connection
  2. Try loading the video again
  3. If on mobile data, verify you have sufficient bandwidth

​
Ad Blockers

Some ad blockers may interfere with YouTube embeds:
  1. Temporarily disable your ad blocker
  2. Refresh the page
  3. Add Track Better to your ad blocker’s allowlist

​
YouTube Restrictions

In some regions or networks, YouTube may be restricted:
  1. Try accessing YouTube directly to verify it works
  2. Use a VPN if YouTube is blocked in your region
  3. If on a work/school network, videos may be blocked by firewall

​
PWA Installation Issues

​
Install Button Not Showing

The Install App button appears based on browser support: Chrome/Edge:
  • Button appears automatically when install criteria are met
  • Must visit the app at least once
  • Must not already be installed
Firefox:
  • No native install prompt (use “Add to Home Screen” manually)
Safari (iOS):
  • No install button (use Share > Add to Home Screen)

​
Manual Installation

On Desktop (Chrome/Edge):
  1. Click the install icon in the address bar
  2. Or go to menu > Install Track Better
On iOS (Safari):
  1. Tap the Share button
  2. Scroll down and tap Add to Home Screen
  3. Name it “Track Better” and tap Add
On Android (Chrome):
  1. Tap the menu (three dots)
  2. Select Add to Home Screen or Install app
  3. Confirm the installation

​
App Not Working After Install

If the installed PWA doesn’t work properly:
  1. Uninstall the app
  2. Clear browser cache and localStorage
  3. Visit the web version and verify it works
  4. Reinstall the PWA

​
Theme Not Switching

If toggling between light and dark mode doesn’t work:

​
Cache the Theme State

The theme preference is stored in localStorage as theme.
  1. Open DevTools > Application > Local Storage
  2. Find the theme key
  3. Change the value to "light" or "dark" manually
  4. Refresh the page

​
Clear Theme Cache

  1. Click the theme toggle button multiple times
  2. Refresh the page
  3. If still not working, clear localStorage:
    • DevTools > Application > Local Storage
    • Right-click > Clear
    • Refresh and set theme again

​
Reset Today’s Workout Not Working

If the “Reset Today’s Workout” button doesn’t clear your progress:

​
Manual Reset

  1. Open DevTools (F12)
  2. Go to Application > Local Storage
  3. Find completedExercises key
  4. Click to edit the JSON value
  5. Remove the entry for today’s date (format: YYYY-MM-DD)
  6. Save and refresh the page

​
Streak Counter Incorrect

If your streak count seems wrong:

​
How Streaks Are Calculated

The app counts consecutive days with at least one completed exercise. The streak calculation in App.jsx:46-65:
  • Starts from today and counts backward
  • Breaks when it finds a day with no completed exercises
  • Only checks the last 365 days

​
Fix Incorrect Streak

Your data in localStorage might have gaps or corruption:
  1. Export your data as backup
  2. Open DevTools > Application > Local Storage
  3. Review completedExercises entries
  4. Look for missing dates or corrupted entries
  5. Manually fix JSON if needed (advanced users only)

​
Export/Import Not Working

​
Export Issues

If clicking Export Data doesn’t download a file:
  1. Check browser download settings
  2. Ensure pop-ups are not blocked
  3. Try a different browser
  4. Manually copy localStorage data (see Data Management)

​
Import Issues

If importing data shows an error: “Invalid file format”:
  • Ensure you’re uploading a JSON file exported from Track Better
  • File must contain completedExercises field
  • Check that JSON is valid (use a JSON validator)
“Failed to parse file”:
  • The JSON file may be corrupted
  • Try opening the file in a text editor to verify format
  • Re-export from the original source

​
Getting More Help

If your issue isn’t covered here:
  1. Check the FAQ for common questions
  2. Review Data Management for storage issues
  3. Open an issue on GitHub
  4. Contact the creator via social links in the Settings tab
Before performing a hard reset or clearing data, always export your data to create a backup. Data loss cannot be recovered without a backup.

Build docs developers (and LLMs) love

Get started for freeTalk to us