rehearshalhub/black_screen_debug.md

Black Screen Debugging Guide

Issue Description

Users are experiencing black screens when navigating in the mobile menu, particularly when clicking the Library button.

Debugging Steps

Step 1: Open Browser Console

1. Open Chrome/Firefox/Safari
2. Press F12 or right-click → "Inspect"
3. Go to "Console" tab
4. Clear existing logs (optional)

Step 2: Reproduce the Issue

1. Resize browser to mobile size (<768px width)
2. Navigate to a band's library: /bands/your-band-id
3. Click "Settings" in bottom navigation
4. Click "Library" in bottom navigation
5. Observe console output

Step 3: Analyze Debug Output

Expected Debug Logs

BottomNavBar - Current band ID: "your-band-id" Path: "/bands/your-band-id"
// ... navigation to settings ...
BottomNavBar - Current band ID: "your-band-id" Path: "/bands/your-band-id/settings/members"
Library click - Navigating to band: "your-band-id"

Common Issues & Solutions

Console Output	Likely Cause	Solution
currentBandId: null	Band context lost	Fix context preservation logic
currentBandId: undefined	URL parsing failed	Debug matchPath logic
No logs at all	Component not rendering	Check routing configuration
Wrong band ID	Stale context	Improve context updating

Step 4: Check Network Requests

1. Go to "Network" tab in dev tools
2. Filter for /bands/* requests
3. Check if band data is being fetched
4. Verify response status codes

Step 5: Examine React Query Cache

1. In console, type: window.queryClient.getQueryData(['band', 'your-band-id'])
2. Check if band data exists in cache
3. Verify data structure matches expectations

Step 6: Test Direct Navigation

1. Manually navigate to /bands/your-band-id
2. Verify page loads correctly
3. Check console for errors
4. Compare with bottom nav behavior

Common Root Causes

1. Band Context Loss

Symptoms: currentBandId: null in console Causes:

• Navigation resets context
• URL parameters not preserved
• matchPath logic failure

Fixes:

// Ensure band ID is preserved in navigation state
// Improve URL parameter extraction
// Add fallback handling

2. Race Conditions

Symptoms: Intermittent black screens Causes:

• Data not loaded before render
• Async timing issues
• State update conflicts

Fixes:

// Add loading states
// Use suspense boundaries
// Implement data fetching guards

3. Routing Issues

Symptoms: Wrong URL or 404 errors Causes:

• Incorrect route paths
• Missing route parameters
• Route configuration errors

Fixes:

// Verify route definitions
// Check parameter passing
// Add route validation

4. Component Rendering

Symptoms: Component doesn't mount Causes:

• Conditional rendering issues
• Error boundaries catching exceptions
• Missing dependencies

Fixes:

// Add error boundaries
// Improve error handling
// Verify component imports

Immediate Fixes to Try

Fix 1: Add Loading State to BandPage

// In BandPage.tsx
if (isLoading) return <div>Loading band data...</div>;
if (!band) return <div>Band not found</div>;

Fix 2: Improve Band Context Preservation

// In BottomNavBar.tsx
const currentBandId = bandMatch?.params?.bandId || 
                     location.state?.bandId || 
                     localStorage.getItem('currentBandId');

Fix 3: Add Error Boundary

// Wrap BandPage with error boundary
<ErrorBoundary fallback={<div>Failed to load band</div>}>
  <BandPage />
</ErrorBoundary>

Debugging Checklist

• Open browser console
• Reproduce black screen issue
• Capture console output
• Check network requests
• Examine React Query cache
• Test direct navigation
• Identify root cause
• Implement targeted fix
• Re-test after fix

Console Output Template

Issue Reproduction:

// Paste console logs here
// Include timestamps if possible
// Note any errors or warnings

Network Requests:

// List relevant network requests
// Note status codes and responses

React Query Cache:

// Show cache contents
// Verify data structure

Root Cause Analysis:

// Identified issue:
// Proposed solution:
// Expected outcome:

Support Information

If you need additional help:

1. Share console output
2. Describe exact reproduction steps
3. Note browser and version
4. Include screenshots if helpful

Contact: Support team or development lead Priority: High (user-facing issue) Impact: Critical (blocks mobile navigation)