> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinfindu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Common issues and solutions for FindU development

# 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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
Error: Cannot find module '@radix-ui/react-dialog'
```

**Solution**: Install dependencies

```bash theme={null}
cd web_app
npm install
```

#### Port already in use

```
Error: Port 5173 is already in use
```

**Solution**: Kill the process or use different port

```bash theme={null}
# 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

```bash theme={null}
cd ios_app
pod install
# Open ios_app.xcworkspace (not .xcodeproj)
```

#### Missing Secrets.xcconfig

**Solution**: Copy example and add credentials

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

**Problem**: Code doesn't pass linting

**Solution**: Fix issues or skip temporarily

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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](/internal/overview)
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

```bash theme={null}
# 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

<Note>
  Most issues are solved by one of: installing dependencies, starting Docker, or configuring environment variables.
</Note>