Troubleshooting

Common issues and how to resolve them. Start with remind doctor — it catches most problems automatically.

The doctor command

Always start here. It checks database, configuration, authentication, and accessibility:

$ remind doctor

remind.
DIAGNOSTICS
────────────────────────────────────────────
  DATABASE           ✓ connected
  CONFIGURATION      ✓ valid
  LICENSE TOKEN      ✓ authenticated
  REMINDERS          ✓ accessible

────────────────────────────────────────────
  ✓ All checks passed.

If any check fails, the error message tells you what's wrong and how to fix it.

Common issues

"command not found: remind"

The remind binary isn't in your PATH.

Fix:

If installed via Homebrew: run brew link remind
If installed via pip: ensure your Python scripts directory is in PATH
Check with: which remind or pip show remind-cli

"Database error" or "could not connect"

The SQLite database is corrupted or inaccessible.

Fix:

Check permissions: ls -la ~/.remind/
Verify the file exists: ls ~/.remind/remind.db
If corrupted, remove and Remind will recreate it: rm ~/.remind/remind.db

Warning

Removing the database deletes all reminders. Back up the file first if you want to recover data.

"Invalid token format"

Your license token doesn't start with remind_.

Fix:

Make sure you're using the full token, e.g. remind_indie_abc123xyz789
Copy the token from your account dashboard at remind.hamzaplojovic.blog
Re-login: remind login remind_indie_abc123xyz789

"AI suggestion failed"

The AI backend is unreachable or your quota is exhausted.

Fix:

Check your internet connection
Verify quota with remind report
Check if using a custom backend URL: remind settings --view
Reminders are still created without AI — use --no-ai as a workaround

"Could not parse due date"

The natural language date parser couldn't understand your input.

Fix: Try more explicit formats:

# These work:
--due "tomorrow 5pm"
--due "friday"
--due "2025-03-15 14:00"
--due "in 2 hours"
--due "next monday 9am"

# These may not work:
--due "whenever"
--due "soon"

Notifications not appearing

The scheduler might not be running, or OS permissions are blocking notifications.

Fix:

Check scheduler status: remind scheduler --status
Enable if not running: remind scheduler --enable
Verify notifications are enabled in settings: remind settings --view
macOS: Check System Settings > Notifications > Remind
Linux: Ensure notify-send is installed
Windows: Check notification center settings

Config file is corrupted

Invalid JSON in the config file.

Fix: Reset to defaults by removing the config file:

$ rm ~/.remind/config.json
$ remind doctor
  CONFIGURATION      ✓ valid

Remind creates a fresh config on next run.

Reset everything

To completely reset Remind to factory state:

# Back up your data first
$ cp ~/.remind/remind.db ~/remind-backup.db

# Remove all data
$ rm -rf ~/.remind/

# Verify clean state
$ remind doctor

Getting help

If none of the above resolves your issue:

GitHub Issues: File a bug at github.com/hamzaplojovic/remind/issues
Email: [email protected]
Twitter: @RemindCLI

When reporting a bug, include the output of:

$ remind doctor
$ remind settings --view
$ python --version

AI Features