Troubleshooting Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.0.0
Last Updated: 2025-01-27
Status: Stable
Target Audience: Developers Troubleshooting common development issues in the Encore Health OS Platform.

---

​

Quick Reference

For detailed solutions, see sections below.

---

​

Diagnostic Workflow

When encountering an issue, follow this workflow:

1. Check Error Message - Read the full error message and stack trace
2. Verify Environment - Ensure .env.local is configured correctly
3. Check Dependencies - Run npm install to ensure packages are up to date
4. Clear Cache - Clear build-cache and restart dev server
5. Check Documentation - Review relevant guides (see Related Documentation)
6. Search Codebase - Look for similar patterns or error handling
7. Check Logs - Review browser console and terminal output

---

​

Build & Dependency Issues

​

npm install Fails

​

Symptoms

• npm ERR! messages during installation
• Package resolution errors
• Permission denied errors

​

Solutions

1. Clear npm cache:
   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install
   
2. Check Node version:
   node --version  # Should be 18.x or 20.x
   
3. Use correct package manager:
   # If using npm
   npm install
   
   # If using pnpm
   pnpm install
   
4. Check for conflicting packages:
   npm ls  # Check for dependency conflicts
   

​

TypeScript Build Errors

​

Symptoms

• TS2307: Cannot find module errors
• Type mismatches
• Missing type definitions

​

Solutions

1. Regenerate Supabase types:
   npx supabase gen types typescript --project-id {project-ref} > src/integrations/supabase/types.ts
   
2. Restart TypeScript server:
   • VS Code: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server”
   • Or reload VS Code window
3. Check import paths:
   // ✅ CORRECT: Use @/ alias
   import { Button } from '@/shared/ui/button';
   
   // ❌ WRONG: Relative paths
   import { Button } from '../../../shared/ui/button';
   
4. Verify tsconfig.json:
   • Check paths configuration for @/ alias
   • Ensure include contains all source files

​

Vite Build Errors

​

Symptoms

• Build fails with module resolution errors
• “Cannot find module” in production build
• Chunk loading errors

​

Solutions

1. Clear Vite cache:
   rm -rf node_modules/.vite
   npm run dev
   
2. Check for dynamic imports:
   // ✅ CORRECT: Use React.lazy for routes
   const Dashboard = lazy(() => import('./Dashboard'));
   
   // ❌ WRONG: Direct imports for routes
   import Dashboard from './Dashboard';
   
3. Verify environment variables:
   • All VITE_ prefixed variables must be set
   • Check .env.local exists and is properly formatted

---

​

TypeScript Errors

​

Missing Type Definitions

​

Symptoms

• TS2307: Cannot find module '@/...'
• TS2339: Property '...' does not exist on type

​

Solutions

1. Regenerate Supabase types:
   npx supabase gen types typescript --project-id {project-ref} > src/integrations/supabase/types.ts
   
2. Install missing type packages:
   npm install --save-dev @types/{package-name}
   
3. Check tsconfig.json paths:
   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   

​

Type Mismatches

​

Symptoms

• TS2322: Type 'X' is not assignable to type 'Y'
• Generic type errors

​

Solutions

1. Check component prop types:
   // Verify prop types match
   interface ComponentProps {
     value: string;  // Not number!
   }
   
2. Use type assertions carefully:
   // ✅ CORRECT: Type guard
   if (typeof value === 'string') {
     // value is string here
   }
   
   // ⚠️ Use sparingly: Type assertion
   const value = data as string;
   
3. Check Supabase query return types:
   const { data, error } = await supabase
     .from('table_name')
     .select('*')
     .single();
   
   // data is typed based on Database types
   

---

​

Supabase Connection Issues

​

”Invalid Supabase URL” Error

​

Symptoms

• Connection fails on app load
• “Invalid Supabase URL” error message

​

Solutions

1. Verify .env.local exists:
   cat .env.local
   # Should contain:
   # VITE_SUPABASE_URL=https://{project-ref}.supabase.co
   # VITE_SUPABASE_PUBLISHABLE_KEY=eyJ...
   
2. Check URL format:
   # ✅ CORRECT
   VITE_SUPABASE_URL=https://abcdefghijklmnop.supabase.co
   
   # ❌ WRONG
   VITE_SUPABASE_URL=https://abcdefghijklmnop.supabase.co/  # Trailing slash
   VITE_SUPABASE_URL=http://abcdefghijklmnop.supabase.co    # HTTP not HTTPS
   
3. Restart dev server:
   # Stop server (Ctrl+C)
   npm run dev
   

​

CORS Errors

​

Symptoms

• CORS policy: No 'Access-Control-Allow-Origin' header
• Requests blocked by browser

​

Solutions

1. Verify Supabase project URL:
   • Check VITE_SUPABASE_URL matches your Supabase project
   • Ensure project is active in Supabase Dashboard
2. Check Supabase CORS settings:
   • Supabase Dashboard → Settings → API
   • Verify allowed origins include your domain
3. For edge functions:
   // Ensure CORS headers in edge functions
   const corsHeaders = {
     'Access-Control-Allow-Origin': '*',
     'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
   };
   

​

“Missing required environment variables” Error

​

Symptoms

• App fails to start
• Error about missing Supabase variables

​

Solutions

1. Check .env.local file:
   # File should exist at project root
   ls -la .env.local
   
2. Verify variable names:
   # ✅ CORRECT: VITE_ prefix for client variables
   VITE_SUPABASE_URL=...
   VITE_SUPABASE_PUBLISHABLE_KEY=...
   
   # ❌ WRONG: Missing VITE_ prefix
   SUPABASE_URL=...
   
3. Copy from .env.example:
   cp .env.example .env.local
   # Then fill in your values
   
4. Restart dev server after changes

---

​

Supabase: Remote migration versions not found

​

Symptoms

• supabase db push fails with Remote migration versions not found in local migrations directory
• CI or deployment jobs fail while reconciling migration history

​

Root Cause

Remote migration history contains versions that do not exist in local supabase/migrations/ files.

​

Resolution Steps

1. Inspect remote history:
   supabase link --project-ref <project-ref>
   supabase migration list
   
2. Compare with local files:
   Get-ChildItem "supabase/migrations/*.sql" | Select-Object Name | Sort-Object Name
   
3. Reconcile each missing version:
   • Preferred: recreate the missing migration SQL file with the exact remote version and commit it
   • If no-op: add a placeholder migration file documenting why it is empty
4. Re-run sync:
   supabase db push
   

​

Prevention

• Always create migration files first (supabase migration new ...)
• Commit migration files before applying to remote
• Avoid direct schema changes in Supabase Dashboard without corresponding migration files

---

​

Authentication Problems

​

Login Fails

​

Symptoms

• Login button does nothing
• Error message on login attempt
• Redirects back to login page

​

Solutions

1. Check Supabase auth configuration:
   // Verify client configuration
   export const supabase = createClient(
     SUPABASE_URL,
     SUPABASE_PUBLISHABLE_KEY,
     {
       auth: {
         storage: localStorage,
         persistSession: true,
         autoRefreshToken: true,
       }
     }
   );
   
2. Check email/password format:
   • Email must be valid format
   • Password must meet Supabase requirements (min 6 characters)
3. Verify user exists:
   • Check Supabase Dashboard → Authentication → Users
   • Verify user is confirmed
4. Check browser console:
   • Look for error messages
   • Check Network tab for failed requests

​

Session Not Persisting

​

Symptoms

• User logged out on page refresh
• Session lost after closing browser

​

Solutions

1. Verify localStorage is enabled:
   // Check browser settings
   // Some browsers block localStorage in private mode
   
2. Check auth configuration:
   auth: {
     storage: localStorage,  // ✅ Should be localStorage
     persistSession: true,   // ✅ Should be true
   }
   
3. Clear browser storage:
   • Open DevTools → Application → Storage
   • Clear localStorage and sessionStorage
   • Try logging in again

​

”Unauthorized” Errors

​

Symptoms

• API calls return 401 Unauthorized
• RLS policies blocking access

​

Solutions

1. Verify user is authenticated:
   const { data: { user } } = await supabase.auth.getUser();
   if (!user) {
     // User not authenticated
   }
   
2. Check RLS policies:
   • Verify policies exist for the table
   • Check policy conditions match user context
   • See Database Development Guide for RLS patterns
3. Verify organization context:
   // Ensure organization_id is set correctly
   const { data: { user } } = await supabase.auth.getUser();
   const orgId = user?.user_metadata?.organization_id;
   

---

​

Performance Issues

​

Slow Build Times

​

Symptoms

• npm run build takes > 5 minutes
• Dev server slow to start

​

Solutions

1. Check bundle size:
   npm run build
   # Check output for large chunks
   
2. Optimize imports:
   // ✅ CORRECT: Tree-shakeable imports
   import { Button } from '@/shared/ui/button';
   
   // ❌ WRONG: Importing entire library
   import * as Icons from 'lucide-react';
   
3. Use lazy loading:
   // ✅ CORRECT: Lazy load routes
   const Dashboard = lazy(() => import('./Dashboard'));
   
   // ❌ WRONG: Direct imports
   import Dashboard from './Dashboard';
   
4. Check for circular dependencies:
   npx madge --circular src/
   

​

Large Bundle Size

​

Symptoms

• Initial bundle > 500KB
• Slow initial page load

​

Solutions

1. Analyze bundle:
   npm run build
   # Review chunk sizes in output
   
2. Use code splitting:
   // Lazy load routes
   const Route = lazy(() => import('./Route'));
   
3. Optimize images:
   • Use WebP format
   • Implement lazy loading for images
   • Use appropriate image sizes
4. Check for duplicate dependencies:
   npm ls | grep duplicate
   

​

Slow Query Performance

​

Symptoms

• Queries take > 1 second
• UI feels sluggish

​

Solutions

1. Check query optimization:
   // ✅ CORRECT: Select only needed columns
   .select('id, name, email')
   
   // ❌ WRONG: Select all columns
   .select('*')
   
2. Use indexes:
   • Check Supabase Dashboard → Database → Indexes
   • Add indexes for frequently queried columns
3. Implement pagination:
   .select('*')
   .range(0, 49)  // First 50 records
   
4. Use QueryClient caching:
   const queryClient = new QueryClient({
     defaultOptions: {
       queries: {
         staleTime: 5 * 60 * 1000,  // 5 minutes
       },
     },
   });
   

---

​

Mobile-Specific Issues

​

Layout Breaks on Mobile

​

Symptoms

• Content overflows screen
• Horizontal scrolling
• Elements overlap

​

Solutions

1. Use responsive utilities:
   // ✅ CORRECT: Responsive classes
   <div className="grid grid-cols-1 md:grid-cols-2">
   
   // ❌ WRONG: Fixed width
   <div className="w-96">
   
2. Use PageContainer:
   // ✅ CORRECT: Consistent responsive padding
   <PageContainer spacing="md">
   
   // ❌ WRONG: Manual padding
   <div className="container mx-auto p-6">
   
3. Check safe areas:
   /* Add safe area insets for fixed elements */
   padding-bottom: calc(1rem + env(safe-area-inset-bottom));
   
4. Test on actual devices:
   • Use browser dev tools mobile emulation
   • Test on real iOS/Android devices

​

Touch Targets Too Small

​

Symptoms

• Buttons hard to tap
• Links difficult to click

​

Solutions

1. Use minimum touch target size:
   // ✅ CORRECT: 44x44px minimum
   <button className="min-w-[44px] min-h-[44px]">
   
   // ❌ WRONG: Too small
   <button className="p-1">
   
2. Add adequate padding:
   <button className="px-4 py-3">  // Adequate padding
   

​

Mobile Navigation Issues

​

Symptoms

• Bottom nav overlaps content
• Menu not opening
• Gestures not working

​

Solutions

1. Add bottom padding for nav:
   <div className="pb-20 md:pb-0">  // Account for bottom nav
   
2. Check z-index:
   <nav className="z-50">  // Nav should be above content
   
3. Verify gesture handlers:
   • Check @/platform/gestures imports
   • Verify gesture components are used correctly

---

​

Cross-Browser Compatibility

​

Safari-Specific Issues

​

Symptoms

• Layout breaks in Safari
• CSS not applying correctly

​

Solutions

1. Check CSS vendor prefixes:
   /* May need -webkit- prefix for Safari */
   -webkit-backdrop-filter: blur(10px);
   backdrop-filter: blur(10px);
   
2. Verify safe area support:
   /* Safari requires env() for safe areas */
   padding-bottom: env(safe-area-inset-bottom);
   
3. Check localStorage support:
   • Safari in private mode blocks localStorage
   • Check for localStorage availability

​

Chrome-Specific Issues

​

Symptoms

• Service worker not updating
• Cache issues

​

Solutions

1. Clear service worker:
   • DevTools → Application → Service Workers
   • Click “Unregister”
   • Hard refresh (Ctrl+Shift+R)
2. Clear cache:
   • DevTools → Application → Clear storage
   • Clear site data

---

​

Git & GitHub CLI Connectivity

​

Verifying Git and GitHub CLI Setup

Use this checklist to verify Git and gh CLI are properly installed, authenticated, and connected to GitHub.

​

Git Verification

1. Check Git installation:
   git --version  # Should show version 2.x or later
   
2. Verify user identity (required for commits):
   git config --global user.name   # Should show your name
   git config --global user.email  # Should show your email
   
   If empty, set them:
   git config --global user.name "Your Name"
   git config --global user.email "you@example.com"
   
3. Verify repository connection:
   git remote -v  # Should show origin pointing to GitHub
   git fetch origin  # Should complete without authentication errors
   
4. Windows line endings (recommended):
   git config --global core.autocrlf input
   
   See Git / Line Endings (Windows) for details.

​

GitHub CLI (gh) Verification

1. Check gh installation:
   gh --version  # Should show version 2.x or later
   
   If missing, install via: winget install GitHub.cli
2. Verify authentication:
   gh auth status  # Should show logged in to github.com
   
   If not logged in, run: gh auth login
3. Verify repository access:
   gh repo view  # Should show repository metadata
   gh api user   # Should return your user JSON
   
4. Check token scopes (if using GitHub Projects):
   gh auth status  # Look for 'project' scope in output
   
   If missing, refresh with: gh auth refresh -s project

​

Authentication Alignment

Both Git and gh should use the same protocol (HTTPS or SSH):

• HTTPS (recommended on Windows): Git remote should be https://github.com/... and gh auth status should show “Git operations protocol: https”
• SSH: Git remote should be git@github.com:... and you should have SSH keys configured

If Git uses HTTPS but gh uses SSH (or vice versa), they may not share credentials. Align them:

• For HTTPS: Ensure Git Credential Manager is installed (git credential-manager --version)
• For SSH: Ensure ssh -T git@github.com succeeds

​

Common Issues

Related: See GITHUB_PROJECT_SPEC_TRACKING_PLAN.md for GitHub Projects integration requirements.

---

​

Git / Line Endings (Windows)

​

Mass “changes” every time you reload the window

​

Symptoms

• After reloading the Cursor/VS Code window (or opening the project), Git shows hundreds of files as modified.
• git status or git diff shows “LF will be replaced by CRLF” (or similar) for many files.
• You did not edit those files; the only difference is line endings.

​

Cause

On Windows, Git can be configured to convert line endings to CRLF in the working copy while the repo stores LF. When the editor or Git “touches” files (e.g. on window reload), the mismatch makes every such file appear changed.

​

One-time fix (do this once)

1. Tell Git to keep LF in the working copy (in this repo):
   git config core.autocrlf input
   
   With input, Git does not convert to CRLF on checkout, so files stay LF.
2. Rewrite working copy to LF so it matches the index (Biome is already set to lineEnding: "lf"):
   npm run format
   
   This rewrites all formatted files to LF. After this, git status should show no (or far fewer) changes.
3. Optional: If you still see line-ending diffs in other files (e.g. outside Biome’s scope), refresh the index:
   git add --renormalize .
   git status
   

​

Prevention

• The repo’s .gitattributes now uses * text=auto eol=lf so that all text files use LF on checkout, regardless of OS.
• Keep core.autocrlf input in this repo so Windows does not introduce CRLF again.

---

​

Quick Reference Table

---

​

Related Documentation

​

Setup & Configuration

• Environment Variables - Environment variable configuration
• Setup Quick Start - First-time developer setup
• PWA Setup - PWA configuration and troubleshooting

​

Development Guides

• Database Development Guide - Database and RLS troubleshooting
• Performance Optimization Guide - Performance debugging
• Testing Setup and Run Guide - Test setup and debugging

​

Standards

• UI/UX Standards - UI/UX troubleshooting
• Spacing & UX Standards - Spacing issues
• Constitution - Core requirements and guardrails

---

Maintained By: Platform Foundation Team