Troubleshooting Guide

Solutions to common issues when working with Sightline.

Map Issues

Map shows blank/gray area

Symptoms: The map container loads but shows only a gray background with no tiles.

Causes & Solutions:

The Mapbox token is not set.

Check your .env.local file exists
Verify the token is set:

.env.local

NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_token_here

Restart the development server after changes

The token is malformed or expired.

Verify token starts with pk. (public token)
Check token at mapbox.com/account/access-tokens
Ensure token has required scopes (default public token works)
Try creating a new token if issues persist

Network blocking Mapbox API requests.

Check browser console for CORS or network errors
Verify firewall/VPN isn't blocking api.mapbox.com
Test with a simple Mapbox example to isolate the issue

App stuck on loading screen

Symptoms: The "Initializing..." loader doesn't disappear, or it shows indefinitely.

Causes & Solutions:

The app uses a unified loading state that waits for both data AND map to be ready. Check both:

Data loading issue:
- Check browser console for network errors
- Verify data source endpoints are accessible
- Check if adapters are returning data
Map not signaling ready:
- Ensure Mapbox token is valid
- Check for Mapbox initialization errors in console
- Verify onMapReady callback is being received

// Debug loading state
const { isLoading } = useData();
const [mapReady, setMapReady] = useState(false);
const appReady = !isLoading && mapReady;

console.log('Loading state:', { isLoading, mapReady, appReady });

Customize loader timeout behavior:

map.config.ts

loader: {
  transitionDuration: 500, // Adjust fade duration
  messages: {
    initializing: 'Loading your map...',
  },
}

Map style not loading

Symptoms: Map loads but uses wrong style or default style.

Solution:

map.config.ts

map: {
  // Ensure valid Mapbox style URLs
  style: 'mapbox://styles/mapbox/dark-v11',
  lightStyle: 'mapbox://styles/mapbox/light-v11',
  darkStyle: 'mapbox://styles/mapbox/dark-v11',
}

Custom styles must be:

Public or owned by your Mapbox account
Format: mapbox://styles/{username}/{style-id}

Map not responding to interactions

Symptoms: Map displays but can't zoom, pan, or click markers.

Solutions:

Check for JavaScript errors in console
Verify no overlay elements blocking interactions
Check CSS pointer-events property on map container
Ensure interactiveLayerIds includes your marker layers

Data Issues

"No incidents to display"

Symptoms: Map loads but shows empty state message.

Causes & Solutions:

Data file doesn't exist at specified path.

Verify file exists in public/data/
Check path in config matches exactly:

map.config.ts

dataSources: [{
  adapterConfig: {
    path: '/data/incidents.json',  // Must start with /
  },
}]

JSON file has syntax errors.

Validate JSON at jsonlint.com
Check for trailing commas, missing quotes
Ensure proper encoding (UTF-8)

# Validate JSON from terminal
cat public/data/incidents.json | python -m json.tool

Path doesn't match file location.

// ❌ Wrong - missing leading slash
adapterConfig: { path: 'data/incidents.json' }

// ❌ Wrong - includes public/
adapterConfig: { path: 'public/data/incidents.json' }

// ✅ Correct
adapterConfig: { path: '/data/incidents.json' }

Filters are excluding all incidents.

Check filter state in React DevTools
Clear all filters using the UI or:

const { resetFilters } = useData();
resetFilters();

Verify incidents match filter criteria (date range, etc.)

Incidents not appearing at correct locations

Symptoms: Markers appear in wrong places on the map.

Solutions:

Check coordinate order — Sightline uses [longitude, latitude]:

{
  "location": {
    "longitude": -112.074,  // X coordinate (East/West)
    "latitude": 33.4484     // Y coordinate (North/South)
  }
}

Verify coordinate range:
- Latitude: -90 to 90
- Longitude: -180 to 180
Check decimal precision — At least 4 decimal places for city-level accuracy

Supabase data not loading

Symptoms: Using Supabase adapter but no data appears.

Solutions:

Check environment variables:

.env.local

NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

Verify RPC functions exist:
- The Supabase adapter uses RPC functions (get_all_incidents, get_incident_by_id)
- Ensure these functions are created in your Supabase project
Check Row Level Security (RLS):
- Ensure RLS policies allow anonymous reads
- Or disable RLS for the incidents table (not recommended for production)
Test with Supabase dashboard:
- Run a query directly in SQL editor
- Verify data exists and columns match expected schema

Theme Issues

Dark mode flickering on page load

Symptoms: Page briefly shows wrong theme before correcting.

Solution: This is a hydration issue. Ensure theme script loads early:

src/app/layout.tsx

<head>
  <script
    dangerouslySetInnerHTML={{
      __html: `
        (function() {
          const theme = localStorage.getItem('theme') || 'system';
          const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
          const isDark = theme === 'dark' || (theme === 'system' && prefersDark);
          document.documentElement.classList.toggle('dark', isDark);
        })();
      `,
    }}
  />
</head>

Theme toggle not working

Solutions:

Verify ThemeProvider wraps your app
Check allowToggle is enabled in config:

map.config.ts

theme: {
  allowToggle: true,
  showToggle: true,
}

Check for CSS conflicts overriding .dark class

Build Issues

TypeScript errors

Common errors and fixes:

Cannot find type 'Incident'

Fix: Import from the @disclosureos/sightline-core package:

import type { Incident } from '@disclosureos/sightline-core';

Type 'string' is not assignable to type 'SiteType'

Fix: Use valid enum values:

import type { SiteType } from '@disclosureos/sightline-core';

const siteType: SiteType = 'urban';  // Must be valid SiteType

See Types Reference for valid values.

Module not found: Can't resolve '@/core'

Fix: Check tsconfig.json paths:

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Build fails on Vercel

Common causes:

Missing environment variables:
- Add all required variables in Vercel dashboard
- Check variable names match exactly
Node.js version mismatch:
- Add .nvmrc or engines in package.json:

package.json

{
  "engines": {
    "node": ">=20"
  }
}

Type errors that pass locally:
- Run pnpm type-check locally before pushing
- Check for case-sensitivity issues (macOS vs Linux)

Performance Issues

Slow initial load

Solutions:

Reduce initial data load:

map.config.ts

controls: {
  incidentFeed: {
    initialCount: 20,  // Load fewer items initially
    pageSize: 20,
  },
}

Use viewport-based loading for large datasets
Enable clustering:

map.config.ts

map: {
  clustering: {
    mode: 'mapbox',  // Native clustering is faster
    radius: 50,
    maxZoom: 14,
  },
}

Map laggy with many markers

Solutions:

Switch to Mapbox native clustering:

clustering: { mode: 'mapbox' }  // Instead of 'react'

Increase cluster radius:

clustering: { radius: 75 }  // Fewer individual markers

Reduce marker complexity — Simpler markers render faster
Use data sampling for 10,000+ incidents

See Performance Guide for detailed optimization.

Development Issues

Hot reload not working

Solutions:

Check for file system issues (especially on Windows)
Restart the development server
Clear Next.js cache:

rm -rf .next
pnpm dev

Check for circular imports

ESLint errors blocking build

Quick fixes:

# Fix auto-fixable issues
pnpm lint:fix

# Check all issues
pnpm lint

For specific rules, add to eslint.config.mjs:

{
  rules: {
    '@typescript-eslint/no-unused-vars': 'warn',  // Downgrade to warning
  },
}

Deployment Issues

Vercel preview not updating

Solutions:

Check deployment logs for errors
Verify branch is connected to Vercel project
Force redeploy from Vercel dashboard
Check build cache isn't stale

Custom domain not working

Solutions:

Verify DNS records are correct
Wait for DNS propagation (up to 48 hours)
Check SSL certificate is provisioned
Verify domain is added in Vercel project settings

Getting More Help

If these solutions don't resolve your issue:

Search existing issues: GitHub Issues
Ask the community: GitHub Discussions
Report a bug: Bug Report Template

When reporting issues, include:

Sightline version
Node.js version
Browser and OS
Steps to reproduce
Error messages and console output
Relevant configuration

Troubleshooting Guide

Solutions to common issues when working with Sightline.

Map Issues

Map shows blank/gray area

Symptoms: The map container loads but shows only a gray background with no tiles.

Causes & Solutions:

The Mapbox token is not set.

Check your .env.local file exists
Verify the token is set:

.env.local

NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_token_here

Restart the development server after changes

The token is malformed or expired.

Verify token starts with pk. (public token)
Check token at mapbox.com/account/access-tokens
Ensure token has required scopes (default public token works)
Try creating a new token if issues persist

Network blocking Mapbox API requests.

Check browser console for CORS or network errors
Verify firewall/VPN isn't blocking api.mapbox.com
Test with a simple Mapbox example to isolate the issue

App stuck on loading screen

Symptoms: The "Initializing..." loader doesn't disappear, or it shows indefinitely.

Causes & Solutions:

The app uses a unified loading state that waits for both data AND map to be ready. Check both:

Data loading issue:
- Check browser console for network errors
- Verify data source endpoints are accessible
- Check if adapters are returning data
Map not signaling ready:
- Ensure Mapbox token is valid
- Check for Mapbox initialization errors in console
- Verify onMapReady callback is being received

// Debug loading state
const { isLoading } = useData();
const [mapReady, setMapReady] = useState(false);
const appReady = !isLoading && mapReady;

console.log('Loading state:', { isLoading, mapReady, appReady });

Customize loader timeout behavior:

map.config.ts

loader: {
  transitionDuration: 500, // Adjust fade duration
  messages: {
    initializing: 'Loading your map...',
  },
}

Map style not loading

Symptoms: Map loads but uses wrong style or default style.

Solution:

map.config.ts

map: {
  // Ensure valid Mapbox style URLs
  style: 'mapbox://styles/mapbox/dark-v11',
  lightStyle: 'mapbox://styles/mapbox/light-v11',
  darkStyle: 'mapbox://styles/mapbox/dark-v11',
}

Custom styles must be:

Public or owned by your Mapbox account
Format: mapbox://styles/{username}/{style-id}

Map not responding to interactions

Symptoms: Map displays but can't zoom, pan, or click markers.

Solutions:

Check for JavaScript errors in console
Verify no overlay elements blocking interactions
Check CSS pointer-events property on map container
Ensure interactiveLayerIds includes your marker layers

Data Issues

"No incidents to display"

Symptoms: Map loads but shows empty state message.

Causes & Solutions:

Data file doesn't exist at specified path.

Verify file exists in public/data/
Check path in config matches exactly:

map.config.ts

dataSources: [{
  adapterConfig: {
    path: '/data/incidents.json',  // Must start with /
  },
}]

JSON file has syntax errors.

Validate JSON at jsonlint.com
Check for trailing commas, missing quotes
Ensure proper encoding (UTF-8)

# Validate JSON from terminal
cat public/data/incidents.json | python -m json.tool

Path doesn't match file location.

// ❌ Wrong - missing leading slash
adapterConfig: { path: 'data/incidents.json' }

// ❌ Wrong - includes public/
adapterConfig: { path: 'public/data/incidents.json' }

// ✅ Correct
adapterConfig: { path: '/data/incidents.json' }

Filters are excluding all incidents.

Check filter state in React DevTools
Clear all filters using the UI or:

const { resetFilters } = useData();
resetFilters();

Verify incidents match filter criteria (date range, etc.)

Incidents not appearing at correct locations

Symptoms: Markers appear in wrong places on the map.

Solutions:

Check coordinate order — Sightline uses [longitude, latitude]:

{
  "location": {
    "longitude": -112.074,  // X coordinate (East/West)
    "latitude": 33.4484     // Y coordinate (North/South)
  }
}

Verify coordinate range:
- Latitude: -90 to 90
- Longitude: -180 to 180
Check decimal precision — At least 4 decimal places for city-level accuracy

Supabase data not loading

Symptoms: Using Supabase adapter but no data appears.

Solutions:

Check environment variables:

.env.local

NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

Verify RPC functions exist:
- The Supabase adapter uses RPC functions (get_all_incidents, get_incident_by_id)
- Ensure these functions are created in your Supabase project
Check Row Level Security (RLS):
- Ensure RLS policies allow anonymous reads
- Or disable RLS for the incidents table (not recommended for production)
Test with Supabase dashboard:
- Run a query directly in SQL editor
- Verify data exists and columns match expected schema

Theme Issues

Dark mode flickering on page load

Symptoms: Page briefly shows wrong theme before correcting.

Solution: This is a hydration issue. Ensure theme script loads early:

src/app/layout.tsx

<head>
  <script
    dangerouslySetInnerHTML={{
      __html: `
        (function() {
          const theme = localStorage.getItem('theme') || 'system';
          const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
          const isDark = theme === 'dark' || (theme === 'system' && prefersDark);
          document.documentElement.classList.toggle('dark', isDark);
        })();
      `,
    }}
  />
</head>

Theme toggle not working

Solutions:

Verify ThemeProvider wraps your app
Check allowToggle is enabled in config:

map.config.ts

theme: {
  allowToggle: true,
  showToggle: true,
}

Check for CSS conflicts overriding .dark class

Build Issues

TypeScript errors

Common errors and fixes:

Cannot find type 'Incident'

Fix: Import from the @disclosureos/sightline-core package:

import type { Incident } from '@disclosureos/sightline-core';

Type 'string' is not assignable to type 'SiteType'

Fix: Use valid enum values:

import type { SiteType } from '@disclosureos/sightline-core';

const siteType: SiteType = 'urban';  // Must be valid SiteType

See Types Reference for valid values.

Module not found: Can't resolve '@/core'

Fix: Check tsconfig.json paths:

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Build fails on Vercel

Common causes:

Missing environment variables:
- Add all required variables in Vercel dashboard
- Check variable names match exactly
Node.js version mismatch:
- Add .nvmrc or engines in package.json:

package.json

{
  "engines": {
    "node": ">=20"
  }
}

Type errors that pass locally:
- Run pnpm type-check locally before pushing
- Check for case-sensitivity issues (macOS vs Linux)

Performance Issues

Slow initial load

Solutions:

Reduce initial data load:

map.config.ts

controls: {
  incidentFeed: {
    initialCount: 20,  // Load fewer items initially
    pageSize: 20,
  },
}

Use viewport-based loading for large datasets
Enable clustering:

map.config.ts

map: {
  clustering: {
    mode: 'mapbox',  // Native clustering is faster
    radius: 50,
    maxZoom: 14,
  },
}

Map laggy with many markers

Solutions:

Switch to Mapbox native clustering:

clustering: { mode: 'mapbox' }  // Instead of 'react'

Increase cluster radius:

clustering: { radius: 75 }  // Fewer individual markers

Reduce marker complexity — Simpler markers render faster
Use data sampling for 10,000+ incidents

See Performance Guide for detailed optimization.

Development Issues

Hot reload not working

Solutions:

Check for file system issues (especially on Windows)
Restart the development server
Clear Next.js cache:

rm -rf .next
pnpm dev

Check for circular imports

ESLint errors blocking build

Quick fixes:

# Fix auto-fixable issues
pnpm lint:fix

# Check all issues
pnpm lint

For specific rules, add to eslint.config.mjs:

{
  rules: {
    '@typescript-eslint/no-unused-vars': 'warn',  // Downgrade to warning
  },
}

Deployment Issues

Vercel preview not updating

Solutions:

Check deployment logs for errors
Verify branch is connected to Vercel project
Force redeploy from Vercel dashboard
Check build cache isn't stale

Custom domain not working

Solutions:

Verify DNS records are correct
Wait for DNS propagation (up to 48 hours)
Check SSL certificate is provisioned
Verify domain is added in Vercel project settings

Getting More Help

If these solutions don't resolve your issue:

Search existing issues: GitHub Issues
Ask the community: GitHub Discussions
Report a bug: Bug Report Template

When reporting issues, include:

Sightline version
Node.js version
Browser and OS
Steps to reproduce
Error messages and console output
Relevant configuration

On this page

On this page