Troubleshooting Guide¶

Common issues and solutions for setting up and running the Micro-Learning Platform API.

Installation Issues¶

"xcode-select: note: install requested for command line developer tools"¶

Problem: macOS is requesting Xcode Command Line Tools installation when trying to use Homebrew.

Why it happens: Homebrew requires Xcode Command Line Tools to compile packages. This is a one-time setup requirement on macOS.

Solution 1: Install Xcode Command Line Tools (Recommended)

# Trigger the installation
xcode-select --install

This will: 1. Show a popup dialog asking to install the tools 2. Click "Install" and wait for the download (10-15 minutes) 3. Accept the license agreement when prompted

Verify installation:

xcode-select -p
# Should output: /Library/Developer/CommandLineTools

Solution 2: Use Alternative Installation Methods

If you don't want to install Xcode Command Line Tools, use these alternatives:

Install Deno:

# Official installer (no Xcode tools needed)
curl -fsSL https://deno.land/install.sh | sh

# Add to PATH (add to ~/.zshrc or ~/.bash_profile)
export PATH="$HOME/.deno/bin:$PATH"

Install Supabase CLI:

# Using npm (if you have Node.js)
npm install -g supabase

# OR using official installer
curl -fsSL https://supabase.com/install.sh | sh

Solution 3: Fix Corrupted Installation

If Xcode tools are installed but not working:

# Reset the installation
sudo xcode-select --reset

# Reinstall
xcode-select --install

# If still having issues, manually download from:
# https://developer.apple.com/download/all/

Supabase Issues¶

Supabase won't start¶

Problem: supabase start fails or hangs.

Solutions:

Check Docker is running:

docker ps
# If error, start Docker Desktop

Check port conflicts:

# Check if ports are in use
lsof -i :54321  # API port
lsof -i :54322  # Database port
lsof -i :54323  # Studio port

# If ports are in use, stop the conflicting service or change ports in supabase/config.toml

Reset Supabase:
```
supabase stop
supabase start
```
Check Docker resources:
Open Docker Desktop
Go to Settings > Resources
Ensure you have at least 4GB RAM allocated
Ensure you have at least 2 CPU cores allocated

"Cannot connect to Docker daemon"¶

Problem: Docker daemon is not running.

Solution:

# Start Docker Desktop application
open -a Docker

# Wait for Docker to start (check the menu bar icon)
# Then verify it's running
docker ps

Database connection errors¶

Problem: API can't connect to Supabase database.

Solutions:

Verify Supabase is running:
```
supabase status
```

Check .env file:

# Ensure .env exists and has correct values
cat .env

# Get correct values
supabase status

Verify Supabase URL:
Local development should use: http://127.0.0.1:54321
Not http://localhost:54321 (can cause issues)

Test database connection:

# Connect directly to PostgreSQL
psql postgresql://postgres:postgres@127.0.0.1:54322/postgres

API Server Issues¶

"Missing Supabase configuration" error¶

Problem: API server can't find environment variables.

Solutions:

Create .env file:

cp env.example .env
# Edit .env with your Supabase credentials

Verify .env file location:
Must be in project root (same directory as deno.json)
Check: ls -la .env

Check environment variables:

# The dev script should show loaded variables
deno task dev
# Look for: "✅ Loaded environment variables from .env file"

Port 8000 already in use¶

Problem: Another service is using port 8000.

Solutions:

Find and stop the conflicting service:

lsof -i :8000
# Kill the process (replace PID with actual process ID)
kill -9 <PID>

Use a different port: Edit src/dev.ts and change:

Deno.serve({ port: 8001 }, ...)  // Use different port

API returns 500 errors¶

Problem: API is running but endpoints return errors.

Solutions:

Check Supabase connection:

# Verify Supabase is running
supabase status

# Test API health endpoint
curl http://localhost:8000/health

Check API logs:
Look at the terminal running deno task dev
Check for error messages

Verify database schema:

# Ensure migrations are applied
supabase db reset

Database Issues¶

Migration errors¶

Problem: Database migrations fail to apply.

Solutions:

Check migration syntax:

# View migration file
cat supabase/migrations/20241229000001_create_microlearning_schema.sql

Reset database:
```
supabase db reset
```
Check for conflicting migrations:
```
supabase migration list
```
Manually apply migration:
Open Supabase Studio: http://127.0.0.1:54323
Go to SQL Editor
Copy migration SQL and run it manually

"Table already exists" errors¶

Problem: Trying to create tables that already exist.

Solution:

# Reset database (drops all tables and recreates)
supabase db reset

Warning: This will delete all data in your local database.

Deno Issues¶

"Permission denied" errors¶

Problem: Deno doesn't have required permissions.

Solution: The deno.json task should include all necessary permissions:

{
  "tasks": {
    "dev": "deno run --allow-net --allow-env --allow-read --watch src/dev.ts"
  }
}

If you're running Deno manually, add the flags:

deno run --allow-net --allow-env --allow-read src/dev.ts

Deno not found¶

Problem: deno command not found.

Solutions:

If installed via installer:

# Add to PATH (add to ~/.zshrc or ~/.bash_profile)
export PATH="$HOME/.deno/bin:$PATH"

# Reload shell
source ~/.zshrc  # or source ~/.bash_profile

If installed via Homebrew:

# Verify installation
brew list deno

# Reinstall if needed
brew reinstall deno

Verify installation:
```
which deno
deno --version
```

Getting Help¶

If you're still experiencing issues:

Check the logs:
API server: Check terminal output
Supabase services: docker logs supabase_db_core (or other container name)
Docker: Check Docker Desktop logs or use docker logs <container-name>
Verify all prerequisites:
Deno installed: deno --version
Supabase CLI installed: supabase --version
Docker running: docker ps
Review documentation:
Database Setup Guide
Developer Guide

Common checks:

# Check all services
supabase status
docker ps
deno --version
supabase --version

# Verify environment
cat .env
ls -la .env