Docs/Troubleshooting
Troubleshooting
Common problems when running StudyMap locally or on a fork, and what actually causes them.
The map tiles come from MapTiler, and unlike the Supabase variables, this one is required - the basemap will not render without it.
Get a free key at cloud.maptiler.com, add it to .env.local as NEXT_PUBLIC_MAPTILER_KEY, and restart the dev server - env vars are only read on boot.
This means the Supabase tables exist for auth but not for the app's own data (saved places, home location, personal calendar events). Code already catches this: isMissingTableError() checks for Postgres error PGRST205 ("table not found in schema cache") and shows a message pointing here instead of a generic failure.
Fix: in the Supabase SQL editor, run every file in supabase/migrations/, in filename order. See SELF-HOSTING.md for the full self-host setup.
If you don't need auth at all, leave the Supabase env vars blank. The map, search, filters, and calendar all work without them - you just lose sign-in, saved places, and personal events.
- No prompt appeared, or it's silently doing nothing:the browser doesn't support the Geolocation API, or the page isn't served over HTTPS (required by most browsers outside
localhost). - "Could not read your location": location permission was denied, or the device couldn't get a fix. Check the browser's site permissions and try again.
- Location seems wrong: some browsers fall back to IP-based location when GPS/Wi-Fi positioning is unavailable, which can be off by kilometers, especially on desktop.
See Install & Offline Usage for what gets cached and how to force a fresh load.
Open an issue at github.com/StudentSuite/StudyMap/issues or email studentsuite3@gmail.com.