Skip to main content

​
Development Troubleshooting

This guide covers common issues you might encounter during FindU development and how to resolve them.

​
Setup Issues

​
Repository Clone Failures

Problem: Can’t clone repositories 
git clone https://github.com/findu-app/web_app.git
# Permission denied or repository not found
Solution:
  1. Ensure you have GitHub organization access
  2. Use HTTPS clone if SSH isn’t set up
  3. Check with team lead for repository access

​
Missing Environment Files

Problem: No .env file in repository Solution: Create from example or get from team 
# Look for example file
cp .env.example .env  # If exists

# Or create new one with required keys
echo "VITE_SUPABASE_URL=your_url_here" > .env
echo "VITE_SUPABASE_ANON_KEY=your_key_here" >> .env

​
Component-Specific Issues

​
Web App

​
”Cannot find module” errors

Error: Cannot find module '@radix-ui/react-dialog'
Solution: Install dependencies 
cd web_app
npm install

​
Port already in use

Error: Port 5173 is already in use
Solution: Kill the process or use different port 
# Find process
lsof -i :5173
# Kill it
kill -9 <PID>

# Or use different port
npm run dev -- --port 5174

​
iOS App

​
”No such module ‘Supabase’”

Solution: Install CocoaPods dependencies 
cd ios_app
pod install
# Open ios_app.xcworkspace (not .xcodeproj)

​
Missing Secrets.xcconfig

Solution: Copy example and add credentials 
cp Secrets.xcconfig.example Secrets.xcconfig
# Edit with your Supabase credentials

​
Database Issues

​
Connection refused

Problem: Can’t connect to Supabase Solution: Check your credentials
  1. Verify .env has correct Supabase URL and keys
  2. Test connection in Supabase dashboard
  3. Check if using dev or prod credentials
  4. Ensure no typos in environment variables

​
Permission denied errors

Problem: RLS policies blocking access Solution:
  1. Check if using correct user role (anon vs service)
  2. Verify RLS policies in Supabase dashboard
  3. Use service role key for admin operations

​
Python/ML Environment

​
Module import errors

Solution: Create and activate virtual environment 
cd matching-algorithm
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate     # Windows
pip install -r requirements.txt

​
Environment Configuration

​
Missing credentials errors

Problem: .env.local has placeholder values Solution: Get real credentials from team lead
  • Required: Supabase project ID, URL, and anon key
  • Optional: Service keys, OAuth credentials

​
Wrong environment credentials

Problem: Using wrong Supabase instance Solution: Update your .env files
  1. Get correct credentials from team lead
  2. Update .env in each repository
  3. Restart your development servers
  4. Verify by checking data in Supabase dashboard

​
Git & GitHub Issues

​
Permission denied (publickey)

Problem: SSH key not configured Solution: Use HTTPS or setup SSH 
# Option 1: Use HTTPS (easier)
git clone https://github.com/findu-app/repo-name.git

# Option 2: Setup SSH key
ssh-keygen -t ed25519 -C "[email protected]"
# Add to GitHub: Settings > SSH keys

​
Pre-commit hook failures

Problem: Code doesn’t pass linting Solution: Fix issues or skip temporarily 
# Fix automatically
npm run lint:fix  # For JS/TS
black .          # For Python

# Skip hooks (emergency only)
git commit --no-verify

​
Performance Issues

​
Slow dependency installation

Solution: Use faster registry 
# npm
npm config set registry https://registry.npmmirror.com

# pip
pip install -i https://pypi.org/simple -r requirements.txt

​
High memory usage

Solution: Limit concurrent processes 
# Limit Node memory
NODE_OPTIONS="--max-old-space-size=4096" npm run dev

# Close unnecessary apps
# Restart Docker Desktop

​
Getting Help

​
Check Documentation

  1. Repository CLAUDE.md files
  2. Internal docs
  3. Component-specific READMEs

​
Ask the Team

  1. Search Slack history in #dev
  2. Post specific error messages
  3. Include steps to reproduce

​
Debug Commands

# System info
uname -a
node --version
python3 --version
docker --version

# Project status
./findu env status
git status
npm list  # In project directory

​
Common Fixes Checklist

When something’s not working, try these in order:
  1. ✓ Is Docker running?
  2. ✓ Are you in the right directory?
  3. ✓ Did you run npm install?
  4. ✓ Is .env.local configured?
  5. ✓ Did you pull latest changes?
  6. ✓ Did you restart the service?
  7. ✓ Check Slack for known issues
Most issues are solved by one of: installing dependencies, starting Docker, or configuring environment variables.