Troubleshooting

This guide helps you diagnose and resolve common issues when using BearFlare.

Common Errors

Solution: Ensure Bear.app is installed and has been opened at least once.

Solution: Install jq via Homebrew: brew install jq

Solution: Verify your API token has D1 Edit permissions. Regenerate the token if needed. See Configuration for details.

Solution: Check that your CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_D1_DATABASE_ID are correct in the Cloudflare dashboard.

Solution: Check ~/.bearflare/bearflare.log for details. Rerun with --debug for more information.

Solution: Normal if using --incremental. For full sync, rerun with --drop for a clean state.

Logs are saved to ~/.bearflare/bearflare.log. Check this file if something goes wrong.

# View recent logs
tail -f ~/.bearflare/bearflare.log

# Search for errors
grep ERROR ~/.bearflare/bearflare.log

Q: Does this sync my actual notes content?
A: Yes! BearFlare syncs both the table structure and your note data.

Q: How does incremental sync work?
A: Incremental sync only syncs notes modified since your last sync, making it faster for large datasets.

Q: Can I sync a single note?
A: Yes, use --note-id <identifier> to sync a specific note.

Q: Will this modify my Bear.app database?
A: No, BearFlare only reads from Bear.app's database. It never modifies it.

Q: What happens if the table already exists in D1?
A: Use the --drop flag to drop the existing table before creating the new schema.

Q: Can I use this on Linux or Windows?
A: No, Bear.app is macOS-only, so this tool requires macOS.