Early Adopter Program Troubleshooting Guide¶

Common Issues and Solutions¶

This guide helps early adopters quickly resolve common issues encountered during the pilot program.

Installation & Setup Issues¶

Issue: usl command not found after installation¶

Symptoms:

$ usl --version
zsh: command not found: usl

Solutions: 1. Check if npm global bin is in PATH:

npm config get prefix
# Add to ~/.zshrc or ~/.bashrc:
export PATH="$PATH:$(npm config get prefix)/bin"
source ~/.zshrc

1. Reinstall USL CLI:

   npm uninstall -g @usl/cli
   npm install -g @usl/cli
   

2. Use npx instead:

   npx @usl/cli --version
   

Issue: VSCode extension not working¶

Symptoms: No syntax highlighting, autocomplete, or error checking

Solutions: 1. Verify extension is installed:

code --list-extensions | grep usl

1. Install manually:
2. Open VSCode
3. Go to Extensions (Cmd/Ctrl+Shift+X)
4. Search "USL"

5. Install "USL Language Support"

6. Reload VSCode:

7. Cmd/Ctrl+Shift+P → "Reload Window"

8. Check language mode:

9. Open .usl file
10. Bottom right corner should show "USL"

11. If not, click and select "USL"

12. Check extension logs:

13. View → Output → Select "USL Language Server"

Issue: Database connection failed¶

Symptoms:

Error: Connection refused - postgresql://localhost:5432

Solutions: 1. Check PostgreSQL is running:

# macOS
brew services list | grep postgresql

# Linux
systemctl status postgresql

# Docker
docker ps | grep postgres

1. Start PostgreSQL:

   # macOS
   brew services start postgresql@15
   
   # Linux
   sudo systemctl start postgresql
   
   # Docker
   docker run -d -p 5432:5432 \
     -e POSTGRES_PASSWORD=password \
     postgres:15
   

2. Verify connection string:

   # Test connection
   psql "postgresql://user:pass@localhost:5432/dbname"
   

3. Check firewall/network:

   telnet localhost 5432
   

Compilation Errors¶

Issue: Entity 'X' not found¶

Symptoms:

Error: Entity 'User' not found in scope
  at line 15, column 20

Solutions: 1. Check import statement:

import myapp.entities.user

1. Verify file structure:

   src/
     entities/
       user.usl  ← Define here
     api/
       auth.usl  ← Import here
   

2. Check entity definition:

   // Make sure it's actually defined
   entity User {
     // ...
   }
   

3. Clear cache and rebuild:

   usl clean
   usl build
   

Issue: Circular dependency detected¶

Symptoms:

Error: Circular dependency detected:
  A.usl → B.usl → C.usl → A.usl

Solutions: 1. Refactor to remove cycle: - Extract common types to separate file - Use forward declarations - Restructure relationships

1. Example fix:

   // Before (circular)
   // user.usl
   entity User {
     posts: [Post] relation(user_id)
   }
   
   // post.usl
   import user
   entity Post {
     author: User relation(user_id)
   }
   
   // After (no cycle)
   // types.usl
   entity User { /* basic fields */ }
   entity Post { /* basic fields */ }
   
   // relationships.usl
   extend User {
     posts: [Post] relation(user_id)
   }
   extend Post {
     author: User relation(user_id)
   }
   

Issue: Type mismatch errors¶

Symptoms:

Error: Type mismatch - expected 'string', got 'int'
  at line 42

Solutions: 1. Check field types:

entity User {
  age: int  // Not string!
}

1. Use type conversion:

   age_string = age.to_string()
   

2. Fix validation:

   input {
     age: int validate(>= 0, <= 150)  // Not string
   }
   

Runtime Errors¶

Issue: Authentication errors¶

Symptoms:

401 Unauthorized - Invalid token

Solutions: 1. Check JWT secret is set:

echo $JWT_SECRET
# If empty, set it:
export JWT_SECRET=$(openssl rand -hex 64)

1. Verify token format:

   # Token should be in header:
   Authorization: Bearer eyJhbGc...
   

2. Check token expiration:

   config {
     jwt: {
       expires_in: 24 hours  // Increase if needed
     }
   }
   

3. Debug token:

   # Decode JWT (without verification)
   echo "eyJhbGc..." | base64 -d
   

Issue: Permission denied errors¶

Symptoms:

403 Forbidden - Insufficient permissions

Solutions: 1. Check user role:

api {
  GET "/admin" {
    auth: required
    roles: [Admin]  // User must have Admin role
  }
}

1. Verify permission rules:

   permissions Post {
     role Author {
       can update Post where author_id == current_user.id
     }
   }
   

2. Debug current user:

   handler {
     log.debug("Current user:", current_user)
     log.debug("User roles:", current_user.roles)
     // ...
   }
   

Issue: Database query errors¶

Symptoms:

Error: column "xyz" does not exist

Solutions: 1. Run migrations:

usl migrate

1. Check schema is up-to-date:

   usl migrate:status
   

2. Reset database (dev only):

   usl db:reset
   usl migrate
   

3. Verify field name:

   entity User {
     email: string  // Use this in queries
   }
   
   query {
     User.where(email == "test@example.com")  // Not "e-mail"
   }
   

Performance Issues¶

Issue: Slow compilation times¶

Symptoms: usl build takes > 30 seconds

Solutions: 1. Enable incremental compilation:

# .usl.config
compiler:
  incremental: true
  cache: true

1. Reduce file count:
2. Combine small entities into larger files

3. Remove unused imports

4. Clear cache:

   usl clean --cache
   

5. Check for circular dependencies:

   usl analyze:dependencies
   

Issue: Slow API response times¶

Symptoms: API requests take > 1 second

Solutions: 1. Enable query logging:

# .usl.config
database:
  log_queries: true
  log_slow_queries: 100ms

1. Add database indexes:

   entity User {
     email: string indexed  // Add index
   }
   

2. Use pagination:

   query {
     User.limit(20).offset(0)  // Don't fetch all records
   }
   

3. Enable caching:

   service UserService {
     get_user(id: uuid): User {
       cache(ttl: 300)  // Cache for 5 minutes
       return User.find(id)
     }
   }
   

4. Optimize queries:

   // Bad
   users = User.all()
   for user in users {
     posts = user.posts.all()  // N+1 query problem
   }
   
   // Good
   users = User.include([posts]).all()  // Single query with join
   

Deployment Issues¶

Issue: Build fails in CI/CD¶

Symptoms: Works locally, fails in CI

Solutions: 1. Check Node version:

# .github/workflows/deploy.yml
- uses: actions/setup-node@v3
  with:
    node-version: '18'  # Match your local version

1. Install dependencies:

   - run: npm ci  # Not npm install
   - run: npm install -g @usl/cli
   

2. Set environment variables:

   env:
     DATABASE_URL: ${{ secrets.DATABASE_URL }}
     JWT_SECRET: ${{ secrets.JWT_SECRET }}
   

3. Check build script:

   // package.json
   {
     "scripts": {
       "build": "usl build --production"
     }
   }
   

Issue: Docker container won't start¶

Symptoms:

Error: Cannot connect to database
Container exits immediately

Solutions: 1. Check logs:

docker logs <container-id>

1. Verify environment variables:

   docker run -e DATABASE_URL="..." -e JWT_SECRET="..." ...
   

2. Use docker-compose:

   # docker-compose.yml
   version: '3.8'
   services:
     app:
       build: .
       ports:
         - "3000:3000"
       environment:
         DATABASE_URL: postgresql://db:5432/mydb
       depends_on:
         - db
     db:
       image: postgres:15
       environment:
         POSTGRES_PASSWORD: password
   

3. Health check:

   # Dockerfile
   HEALTHCHECK --interval=30s --timeout=3s \
     CMD curl -f http://localhost:3000/health || exit 1
   

Discord & Support Issues¶

Issue: Not receiving Discord notifications¶

Solutions: 1. Check notification settings: - Right-click channel → Notification Settings - Enable for @mentions and important channels

1. Check server mute:
2. Right-click server icon → Notification Settings

3. Unmute server

4. Enable desktop notifications:

5. User Settings → Notifications
6. Enable Desktop Notifications

Issue: Can't find help in Discord¶

Solutions: 1. Use search:

in:#help database error
from:USL-Team authentication

1. Check pinned messages:

2. Click pushpin icon (top right)

3. Use proper channel:

4. help - Technical questions¶

5. feedback - Feature requests¶

6. bugs - Bug reports¶

7. emergency - Production issues only¶

Getting More Help¶

When to Ask for Help¶

Ask immediately if: - Production system down - Security vulnerability - Data loss risk - Complete blocker (can't proceed)

Ask within 24 hours if: - Compilation error you can't solve - Deployment failure - Performance degradation - Feature confusion

Ask during office hours if: - General questions - Best practices - Architecture review - Learning new features

How to Ask Good Questions¶

✅ Good Question:

**Issue**: Getting "Entity 'Post' not found" error

**Code**: 
// api/feed.usl
import entities.post

api FeedAPI {
  GET "/feed" {
    posts = Post.all()  // ← Error here
  }
}

**Error**:
Error: Entity 'Post' not found in scope
  at api/feed.usl:5:13

**What I've tried**:
- Verified Post.usl exists in entities/
- Tried different import syntax
- Ran `usl clean && usl build`
- Checked docs on imports

**Environment**:
- USL v1.0.5
- macOS 14.2
- Node 18.16.0

❌ Bad Question:

my code doesnt work help

Support Channels Priority¶

1. Search first: Discord, Docs, GitHub Issues
2. Discord #help: Most questions
3. Office Hours: Complex questions, architecture
4. Email: Sensitive issues
5. 1-on-1: Strategic discussions
6. Emergency: Production-critical only

Useful Commands¶

Diagnostic Commands¶

# Check USL version
usl --version

# Check environment
usl env:check

# Analyze project
usl analyze

# Check dependencies
usl deps:check

# Database status
usl migrate:status

# Run health check
usl health

Debug Mode¶

# Verbose output
usl build --verbose

# Debug logging
usl dev --log-level=debug

# Trace compilation
usl build --trace

Reset Commands (Development Only)¶

# Clean build artifacts
usl clean

# Reset database
usl db:reset

# Clear cache
usl clean --cache

# Fresh start
usl clean && usl db:reset && usl migrate && usl build

Still Stuck?¶

1. Check Discord #help channel
2. Attend Office Hours (Tuesday/Thursday)
3. Email early-adopters@usl.dev
4. Schedule 1-on-1 for complex issues
5. Tag @emergency for production issues

Remember: We want you to succeed! Don't hesitate to ask for help.

Last Updated: January 15, 2026