Troubleshooting Guide

Solutions for common issues and error messages.

Table of Contents

1. Photos Not Syncing
2. Listings Not Appearing in Search
3. Magic Links Not Working
4. Sync Stuck in Running
5. Rate Limit Errors from Bridge
6. Error Code Reference
7. Contact Form Not Working
8. Map Not Loading
9. Slow Performance
10. Mobile Display Issues

Photos Not Syncing

Symptoms

• Listings show but photos are missing
• photo_count is 0 in database
• MediaURL is null in raw data

Root Cause

Using $expand=Media in Bridge API queries causes MediaURL to return null. This was confirmed by Bridge Interactive support in January 2026.

Solution

DO NOT use $expand=Media in Bridge queries. Media is already embedded in the Property response.

Wrong (causes null MediaURL):

/Property?$expand=Media&$top=200

Correct (MediaURL populated):

/Property?$top=200

Verification

Check if listings have media:

SELECT l.id, l.mls_number, l.photo_count,
       jsonb_array_length(l.raw->'Media') as raw_media_count
FROM listings l
WHERE workspace_id = 'your-workspace-id'
LIMIT 10;

Check media URLs in raw data:

SELECT l.raw->'Media'->0->>'MediaURL' as first_photo_url
FROM listings l
WHERE workspace_id = 'your-workspace-id'
AND l.raw->'Media' IS NOT NULL
LIMIT 5;

Fix Existing Data

Re-run full sync to repopulate photos:

1. Admin App → Workspace → Import Task → Run (Full Sync)
2. Wait for completion
3. Verify photos appear

Listings Not Appearing in Search

Symptoms

• Listings exist in Postgres but search returns nothing
• Filters show 0 results
• Facet counts are empty

Diagnosis

Check if listings exist in Postgres:

SELECT COUNT(*) FROM listings WHERE workspace_id = 'your-workspace-id';

Check Typesense collection:

curl "https://your-typesense-host:8108/collections/workspace_slug" \
  -H "X-TYPESENSE-API-KEY: your-key"

Solutions

1. Typesense collection doesn't exist

Create collection and reindex:

# The sync process should auto-create, but if needed:
# Check packages/typesense for collection schema

Then run full sync to reindex all listings.

2. Typesense indexing failed during sync

Check sync run for errors:

SELECT * FROM sync_runs
WHERE workspace_id = 'your-workspace-id'
ORDER BY started_at DESC
LIMIT 5;

Reindex by running full sync:

• Admin App → Import Task → Run (Full Sync)

3. Schema mismatch

If fields were added/changed:

1. Export existing documents (if needed)
2. Delete collection
3. Run full sync to recreate with new schema

4. Workspace slug mismatch

Typesense collections are named by workspace slug. Verify:

SELECT id, slug FROM workspaces WHERE id = 'your-workspace-id';

Magic Links Not Working

Symptom: Link redirects to wrong domain

Cause: Domain not in Supabase Redirect URLs

Solution:

1. Go to Supabase Dashboard → Authentication → URL Configuration
2. Add https://your-domain.com/** to Redirect URLs
3. Save and test with new magic link

Symptom: Link goes to correct domain but user not authenticated

Cause: Callback route issue or missing code exchange

Diagnosis:

1. Check browser console for errors
2. Check Supabase Auth logs

Solution:

1. Verify /auth/callback/route.ts exists and handles code exchange
2. Check middleware allows /auth/callback route
3. Ensure exchangeCodeForSession() is called

Symptom: "Invalid or expired link" error

Cause: Magic link expired (default 1 hour) or already used

Solution:

1. Request new magic link
2. Check email delivery time (delays can cause expiration)
3. Ensure link is only clicked once

Symptom: Email never arrives

Causes:

• Spam folder
• Email delivery issues
• Invalid email address

Diagnosis: Check Supabase Auth logs for send attempts.

Solution:

1. Check spam/junk folder
2. Try alternate email
3. Verify email in Supabase dashboard

Sync Stuck in Running

Symptoms

• Sync shows "running" for >30 minutes
• New syncs won't start
• started_at is old, no ended_at

Diagnosis

SELECT id, started_at, ended_at, status, records_fetched
FROM sync_runs
WHERE workspace_id = 'your-workspace-id'
AND status = 'running';

Solutions

1. Cancel via Admin UI

Admin App → Workspace → Sync Runs → Cancel button

2. Cancel via SQL

UPDATE sync_runs
SET status = 'error',
    error = 'Manually cancelled - stuck sync',
    ended_at = NOW()
WHERE id = 'stuck-sync-run-id'
AND status = 'running';

3. Prevent future issues

• Check for network timeouts in logs
• Ensure worker has sufficient timeout (300s for Vercel)
• Monitor memory usage during large syncs

Rate Limit Errors from Bridge

Symptoms

• HTTP 429 errors in sync logs
• Sync fails partway through
• "Too Many Requests" error message

Understanding Rate Limits

Bridge Interactive typically allows:

• 1-2 requests per second for bulk operations
• Higher limits for simple queries

Our sync worker includes 100ms delays between pages.

Solutions

1. Backoff and retry

The sync worker has built-in retry with exponential backoff. Usually waiting 5-10 minutes and retrying resolves the issue.

2. Reduce sync frequency

Change import task cadence:

• Admin App → Import Task → Edit → Cadence
• Switch from hourly to 6h or daily

3. Optimize filters

More specific filters = fewer pages to fetch:

# More specific (fewer results)
City eq 'Miami Beach' and StandardStatus eq 'Active' and ListPrice ge 1000000

# Less specific (more results, more pages)
StandardStatus eq 'Active'

4. Contact Bridge support

If persistent, contact support@bridgeinteractive.com about:

• Your rate limit tier
• Potential limit increases
• Best practices for bulk operations

Error Code Reference

HTTP Status Codes

Bridge API Error Codes

Supabase Error Codes

Application Error Messages

Contact Form Not Working

Symptoms

• Form submits but no email received
• Form shows error on submit
• Rate limit errors

Diagnosis

1. Check browser console for errors
2. Check API response from /api/contact
3. Check rate limiting (5 req/min for auth tier)

Solutions

Rate limited

Wait 1 minute, or if testing, temporarily increase limit.

Email not sending

1. Check email configuration in environment variables
2. Verify recipient email is valid
3. Check spam folder

Validation errors

1. Ensure all required fields filled
2. Check email format
3. Verify message length within limits

Map Not Loading

Symptoms

• Map container shows but no map tiles
• "Map unavailable" error
• Console shows API errors

Diagnosis

1. Check browser console for errors
2. Verify map API key in environment variables
3. Check if listings have coordinates

Solutions

Missing API key

Add map provider API key to environment variables.

Missing coordinates

SELECT COUNT(*) FROM listings
WHERE workspace_id = 'your-workspace-id'
AND (latitude IS NULL OR longitude IS NULL);

If many listings lack coordinates, check field mapping for latitude and longitude.

API quota exceeded

Check map provider dashboard for usage limits.

Slow Performance

Symptoms

• Pages take >3 seconds to load
• Search is sluggish
• Timeouts on large workspaces

Diagnosis Areas

1. Database: Check query performance
2. Typesense: Check search latency
3. Network: Check asset loading
4. Client: Check browser performance

Solutions

Slow database queries

-- Check for slow queries
SELECT * FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Add indexes for common query patterns:

CREATE INDEX IF NOT EXISTS idx_listings_workspace_status
ON listings(workspace_id, standard_status);

Slow search

1. Check Typesense server resources
2. Optimize search queries (limit facets, use filters)
3. Consider caching common searches

Large images

1. Use optimized image formats (WebP)
2. Implement lazy loading
3. Use CloudFront/CDN caching

Mobile Display Issues

Symptoms

• Layout broken on mobile
• Touch targets too small
• Content overflowing

Solutions

Layout issues

1. Check Tailwind responsive classes
2. Test with browser dev tools mobile view
3. Verify viewport meta tag

Touch targets

Ensure buttons/links are at least 44x44px on mobile.

Overflow

Check for fixed widths that don't scale:

/* Bad */
width: 400px;

/* Good */
width: 100%;
max-width: 400px;

Quick Diagnostic Commands

Check system health

curl https://your-domain.com/api/health

Check recent sync runs

SELECT started_at, status, records_fetched, error
FROM sync_runs
WHERE workspace_id = 'xxx'
ORDER BY started_at DESC
LIMIT 10;

Check listing counts

SELECT standard_status, COUNT(*)
FROM listings
WHERE workspace_id = 'xxx'
GROUP BY standard_status;

Check for missing photos

SELECT COUNT(*) FROM listings
WHERE workspace_id = 'xxx'
AND photo_count = 0;

Check MLS connection status

SELECT status, last_synced_at, error
FROM mls_connections
WHERE workspace_id = 'xxx';

Getting Help

1. Check this guide for common issues
2. Check Runbook for operational procedures
3. Check Sentry for error details at your configured Sentry dashboard
4. Check service status pages for dependencies
5. Contact support with:
   • Workspace ID
   • Steps to reproduce
   • Error messages
   • Screenshots/logs