​

Development Troubleshooting

​

Setup Issues

​

Repository Clone Failures

git clone https://github.com/findu-app/web_app.git
# Permission denied or repository not found

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

# 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'

cd web_app
npm install

​

Port already in use

Error: Port 5173 is already in use

# 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’”

cd ios_app
pod install
# Open ios_app.xcworkspace (not .xcodeproj)

​

Missing Secrets.xcconfig

cp Secrets.xcconfig.example Secrets.xcconfig
# Edit with your Supabase credentials

​

Database Issues

​

Connection refused

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

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

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

• Required: Supabase project ID, URL, and anon key
• Optional: Service keys, OAuth credentials

​

Wrong environment credentials

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)

# 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 "your-email@example.com"
# Add to GitHub: Settings > SSH keys

​

Pre-commit hook failures

# 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

# npm
npm config set registry https://registry.npmmirror.com

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

​

High memory usage

# 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

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