Encore OS — Documentation

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

Quick Reference

Issue Category	Common Symptoms	Quick Fix
Build Errors	`npm install` fails, TypeScript errors	Check Node version, clear cache
Supabase Connection	”Invalid Supabase URL”, CORS errors	Verify `.env.local` variables
Authentication	Login fails, session not persisting	Check auth configuration
TypeScript Errors	Type mismatches, missing types	Regenerate Supabase types
Performance	Slow builds, large bundle size	Check lazy loading, optimize imports
Mobile Issues	Layout breaks, touch targets too small	Verify responsive breakpoints

For detailed solutions, see sections below.

Diagnostic Workflow

When encountering an issue, follow this workflow:

Check Error Message - Read the full error message and stack trace

Verify Environment - Ensure .env.local is configured correctly

Check Dependencies - Run npm install to ensure packages are up to date

Clear Cache - Clear build-cache and restart dev server

Check Documentation - Review relevant guides (see Related Documentation)

Search Codebase - Look for similar patterns or error handling

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

Clear npm cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Check Node version:

node --version  # Should be 18.x or 20.x

Use correct package manager:

# If using npm
npm install

# If using pnpm
pnpm install

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

Regenerate Supabase types:

npx supabase gen types typescript --project-id {project-ref} > src/integrations/supabase/types.ts

Restart TypeScript server:

VS Code: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server”
Or reload VS Code window

Check import paths:

// ✅ CORRECT: Use @/ alias
import { Button } from '@/shared/ui/button';

// ❌ WRONG: Relative paths
import { Button } from '../../../shared/ui/button';

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

Clear Vite cache:

rm -rf node_modules/.vite
npm run dev

Check for dynamic imports:

// ✅ CORRECT: Use React.lazy for routes
const Dashboard = lazy(() => import('./Dashboard'));

// ❌ WRONG: Direct imports for routes
import Dashboard from './Dashboard';

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

Regenerate Supabase types:

npx supabase gen types typescript --project-id {project-ref} > src/integrations/supabase/types.ts

Install missing type packages:

npm install --save-dev @types/{package-name}

Check tsconfig.json paths:

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

Type Mismatches

Symptoms

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

Solutions

Check component prop types:

// Verify prop types match
interface ComponentProps {
  value: string;  // Not number!
}

Use type assertions carefully:

// ✅ CORRECT: Type guard
if (typeof value === 'string') {
  // value is string here
}

// ⚠️ Use sparingly: Type assertion
const value = data as string;

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

Verify .env.local exists:

cat .env.local
# Should contain:
# VITE_SUPABASE_URL=https://{project-ref}.supabase.co
# VITE_SUPABASE_PUBLISHABLE_KEY=eyJ...

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

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

Verify Supabase project URL:

Check VITE_SUPABASE_URL matches your Supabase project
Ensure project is active in Supabase Dashboard

Check Supabase CORS settings:

Supabase Dashboard → Settings → API
Verify allowed origins include your domain

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

Check .env.local file:

# File should exist at project root
ls -la .env.local

Verify variable names:

# ✅ CORRECT: VITE_ prefix for client variables
VITE_SUPABASE_URL=...
VITE_SUPABASE_PUBLISHABLE_KEY=...

# ❌ WRONG: Missing VITE_ prefix
SUPABASE_URL=...

Copy from .env.example:

cp .env.example .env.local
# Then fill in your values

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

Inspect remote history:

supabase link --project-ref <project-ref>
supabase migration list

Compare with local files:

Get-ChildItem "supabase/migrations/*.sql" | Select-Object Name | Sort-Object Name

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

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

Symptoms

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

Solutions

Check Supabase auth configuration:

// Verify client configuration
export const supabase = createClient(
  SUPABASE_URL,
  SUPABASE_PUBLISHABLE_KEY,
  {
    auth: {
      storage: localStorage,
      persistSession: true,
      autoRefreshToken: true,
    }
  }
);

Check email/password format:

Email must be valid format
Password must meet Supabase requirements (min 6 characters)

Verify user exists:

Check Supabase Dashboard → Authentication → Users
Verify user is confirmed

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

Verify localStorage is enabled:

// Check browser settings
// Some browsers block localStorage in private mode

Check auth configuration:

auth: {
  storage: localStorage,  // ✅ Should be localStorage
  persistSession: true,   // ✅ Should be true
}

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

Verify user is authenticated:

const { data: { user } } = await supabase.auth.getUser();
if (!user) {
  // User not authenticated
}

Check RLS policies:

Verify policies exist for the table
Check policy conditions match user context
See Database Development Guide for RLS patterns

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

Check bundle size:

npm run build
# Check output for large chunks

Optimize imports:

// ✅ CORRECT: Tree-shakeable imports
import { Button } from '@/shared/ui/button';

// ❌ WRONG: Importing entire library
import * as Icons from 'lucide-react';

Use lazy loading:

// ✅ CORRECT: Lazy load routes
const Dashboard = lazy(() => import('./Dashboard'));

// ❌ WRONG: Direct imports
import Dashboard from './Dashboard';

Check for circular dependencies:

npx madge --circular src/

Large Bundle Size

Symptoms

Initial bundle > 500KB
Slow initial page load

Solutions

Analyze bundle:

npm run build
# Review chunk sizes in output

Use code splitting:

// Lazy load routes
const Route = lazy(() => import('./Route'));

Optimize images:

Use WebP format
Implement lazy loading for images
Use appropriate image sizes

Check for duplicate dependencies:

npm ls | grep duplicate

Slow Query Performance

Symptoms

Queries take > 1 second
UI feels sluggish

Solutions

Check query optimization:

// ✅ CORRECT: Select only needed columns
.select('id, name, email')

// ❌ WRONG: Select all columns
.select('*')

Use indexes:

Check Supabase Dashboard → Database → Indexes
Add indexes for frequently queried columns

Implement pagination:

.select('*')
.range(0, 49)  // First 50 records

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

Use responsive utilities:

// ✅ CORRECT: Responsive classes
<div className="grid grid-cols-1 md:grid-cols-2">

// ❌ WRONG: Fixed width
<div className="w-96">

Use PageContainer:

// ✅ CORRECT: Consistent responsive padding
<PageContainer spacing="md">

// ❌ WRONG: Manual padding
<div className="container mx-auto p-6">

Check safe areas:

/* Add safe area insets for fixed elements */
padding-bottom: calc(1rem + env(safe-area-inset-bottom));

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

Use minimum touch target size:

// ✅ CORRECT: 44x44px minimum
<button className="min-w-[44px] min-h-[44px]">

// ❌ WRONG: Too small
<button className="p-1">

Add adequate padding:

<button className="px-4 py-3">  // Adequate padding

Symptoms

Bottom nav overlaps content
Menu not opening
Gestures not working

Solutions

Add bottom padding for nav:

<div className="pb-20 md:pb-0">  // Account for bottom nav

Check z-index:

<nav className="z-50">  // Nav should be above content

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

Check CSS vendor prefixes:

/* May need -webkit- prefix for Safari */
-webkit-backdrop-filter: blur(10px);
backdrop-filter: blur(10px);

Verify safe area support:

/* Safari requires env() for safe areas */
padding-bottom: env(safe-area-inset-bottom);

Check localStorage support:

Safari in private mode blocks localStorage
Check for localStorage availability

Chrome-Specific Issues

Symptoms

Service worker not updating
Cache issues

Solutions

Clear service worker:
- DevTools → Application → Service Workers
- Click “Unregister”
- Hard refresh (Ctrl+Shift+R)
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

Check Git installation:

git --version  # Should show version 2.x or later

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"

Verify repository connection:

git remote -v  # Should show origin pointing to GitHub
git fetch origin  # Should complete without authentication errors

Windows line endings (recommended):

git config --global core.autocrlf input

See Git / Line Endings (Windows) for details.

GitHub CLI (`gh`) Verification

Check gh installation:

gh --version  # Should show version 2.x or later

If missing, install via: winget install GitHub.cli

Verify authentication:

gh auth status  # Should show logged in to github.com

If not logged in, run: gh auth login

Verify repository access:

gh repo view  # Should show repository metadata
gh api user   # Should return your user JSON

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

Issue	Solution
`git: command not found`	Install Git for Windows; restart terminal
`gh: command not found`	Install GitHub CLI; restart terminal; verify PATH
`Permission denied (publickey)`	SSH key not loaded or not added to GitHub; or switch to HTTPS
`HTTP 403` / `could not read Username`	Re-authenticate: `gh auth login` and/or clear stale credentials in Windows Credential Manager
Wrong GitHub user	`gh auth switch` (newer gh) or `gh auth logout` then `gh auth login`

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)

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.

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.

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

Issue	Quick Fix	Detailed Guide
Git/gh not connected	`git fetch origin`, `gh auth status`	Git & GitHub CLI Connectivity
Mass changes on reload (Windows)	`git config core.autocrlf input` then `npm run format`	Git / Line Endings
Build fails	`npm cache clean --force && npm install`	Build Issues
TypeScript errors	Restart TS server, regenerate types	TypeScript Errors
Supabase connection	Check `.env.local` variables	Supabase Issues
Auth not working	Verify auth config, check localStorage	Authentication
Slow performance	Check lazy loading, optimize queries	Performance
Mobile layout breaks	Use responsive classes, PageContainer	Mobile Issues
Browser compatibility	Check vendor prefixes, safe areas	Cross-Browser

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

​Quick Reference

​Diagnostic Workflow

​Build & Dependency Issues

​npm install Fails

​Symptoms

​Solutions

​TypeScript Build Errors

​Symptoms

​Solutions

​Vite Build Errors

​Symptoms

​Solutions

​TypeScript Errors

​Missing Type Definitions

​Symptoms

​Solutions

​Type Mismatches

​Symptoms

​Solutions

​Supabase Connection Issues

​”Invalid Supabase URL” Error

​Symptoms

​Solutions

​CORS Errors

​Symptoms

​Solutions

​“Missing required environment variables” Error

​Symptoms

​Solutions

​Supabase: Remote migration versions not found

​Symptoms

​Root Cause

​Resolution Steps

​Prevention

​Authentication Problems

​Login Fails

​Symptoms

​Solutions

​Session Not Persisting

​Symptoms

​Solutions

​”Unauthorized” Errors

​Symptoms

​Solutions

​Performance Issues

​Slow Build Times

​Symptoms

​Solutions

​Large Bundle Size

​Symptoms

​Solutions

​Slow Query Performance

​Symptoms

​Solutions

​Mobile-Specific Issues

​Layout Breaks on Mobile

​Symptoms

​Solutions

​Touch Targets Too Small

​Symptoms

​Solutions

​Mobile Navigation Issues

​Symptoms

​Solutions

​Cross-Browser Compatibility

​Safari-Specific Issues

​Symptoms

​Solutions

​Chrome-Specific Issues

​Symptoms

​Solutions

​Git & GitHub CLI Connectivity

​Verifying Git and GitHub CLI Setup

​Git Verification

​GitHub CLI (gh) Verification

​Authentication Alignment

​Common Issues

​Git / Line Endings (Windows)

​Mass “changes” every time you reload the window

​Symptoms

Quick Reference

Diagnostic Workflow

Build & Dependency Issues

npm install Fails

Symptoms

Solutions

TypeScript Build Errors

Symptoms

Solutions

Vite Build Errors

Symptoms

Solutions

TypeScript Errors

Missing Type Definitions

Symptoms

Solutions

Type Mismatches

Symptoms

Solutions

Supabase Connection Issues

”Invalid Supabase URL” Error

Symptoms

Solutions

CORS Errors

Symptoms

Solutions

“Missing required environment variables” Error

Symptoms

Solutions

Supabase: Remote migration versions not found

Symptoms

Root Cause

Resolution Steps

Prevention

Authentication Problems

Login Fails

Symptoms

Solutions

Session Not Persisting

Symptoms

Solutions

”Unauthorized” Errors

Symptoms

Solutions

Performance Issues

Slow Build Times

Symptoms

Solutions

Large Bundle Size

Symptoms

Solutions

Slow Query Performance

Symptoms

Solutions

Mobile-Specific Issues

Layout Breaks on Mobile

Symptoms

Solutions

Touch Targets Too Small

Symptoms

Solutions

Mobile Navigation Issues

Symptoms

Solutions

Cross-Browser Compatibility

Safari-Specific Issues

Symptoms

Solutions

Chrome-Specific Issues

Symptoms

Solutions

Git & GitHub CLI Connectivity

Verifying Git and GitHub CLI Setup

Git Verification

GitHub CLI (`gh`) Verification

Authentication Alignment

Common Issues

Git / Line Endings (Windows)

Mass “changes” every time you reload the window

Symptoms