Skip to main content

​
Troubleshooting

This guide covers common issues you may encounter when developing SkyTeam ROBLOX and their solutions.

​
Database Issues

Error:
Error: connect ECONNREFUSED 127.0.0.1:5432
Solutions:
# macOS
brew services list

# Linux
sudo systemctl status postgresql

# Windows (in Services)
services.msc
Common causes:
  • PostgreSQL service not running
  • Incorrect DATABASE_URL in .env
  • Database doesn’t exist
  • Wrong credentials
Error:
Error: relation "users" does not exist
Solution:
# Push schema to database
pnpm db:push
If that doesn’t work:
# Drop database and recreate (WARNING: loses all data)
psql -c "DROP DATABASE skyteam;"
psql -c "CREATE DATABASE skyteam;"
pnpm db:push
Error:
Port 4983 is already in use
Solution:
# Find process using port
lsof -i :4983

# Kill the process
kill -9 <PID>

# Or use a different port
pnpm --filter @skyteam/database db:studio --port 5000
Issue: Running db:generate doesn’t create migration filesSolution:
# Ensure you're in the database package
cd packages/database

# Run generate command
pnpm db:generate

# Check drizzle.config.ts exists
ls -la drizzle.config.ts
Make sure your schema changes are saved before generating migrations.

​
Discord Bot Issues

Error:
Error [TokenInvalid]: An invalid token was provided
Solutions:
  1. Verify token in .env: 
    cat .env | grep DISCORD_TOKEN
  2. Get new token from Discord Developer Portal:
  3. Ensure no extra spaces: 
    # Correct
DISCORD_TOKEN="MTIzNDU2Nzg5MDEyMzQ1Njc4OQ..."

# Incorrect (has spaces)
DISCORD_TOKEN=" MTIzNDU2Nzg5MDEyMzQ1Njc4OQ... "
Issue: Slash commands not appearing in DiscordSolutions:
  1. Verify bot permissions:
    • Bot needs applications.commands scope
    • Reinvite bot with correct OAuth2 URL
  2. Check guild ID: 
    # Verify DISCORD_HOME_GUILD_ID in .env
cat .env | grep DISCORD_HOME_GUILD_ID
  3. Wait for command sync:
    • Guild commands sync instantly
    • Global commands take up to 1 hour
  4. Restart Discord client:
Error:
Error: Cannot find module '@skyteam/database'
Solution:
# Rebuild database package
pnpm --filter @skyteam/database build

# Reinstall dependencies
pnpm install

# Restart bot
pnpm --filter @skyteam/client dev

​
API Issues

Error:
Error: listen EADDRINUSE: address already in use :::4000
Solutions:
# macOS/Linux
lsof -i :4000

# Windows
netstat -ano | findstr :4000
Error:
Access to fetch at 'http://localhost:4000' from origin 'http://localhost:3000' 
has been blocked by CORS policy
Solution:Check the API CORS configuration in apps/api/src/index.ts:
app.use(cors({
  origin: [
    'http://localhost:3000',  // web
    'http://localhost:3001'   // admin
  ],
  credentials: true
}));
Ensure your frontend URL is in the allowed origins list.
Issue: API endpoints returning internal server errorsDebugging steps:
  1. Check API logs: 
    pnpm --filter @skyteam/api dev
# Watch console output for errors
  2. Verify database connection: 
    pnpm db:studio
# If this works, database is connected
  3. Check environment variables: 
    cat .env
# Ensure all required vars are set
  4. Enable debug logging: 
    // In apps/api/src/index.ts
app.use((req, res, next) => {
  console.log(`${req.method} ${req.path}`);
  next();
});

​
Build Issues

Error:
Error: Type 'X' is not assignable to type 'Y'
Solutions:
  1. Clear TypeScript cache: 
    # Remove build artifacts
rm -rf apps/*/dist apps/*/.next packages/*/dist

# Remove TypeScript caches
find . -name "*.tsbuildinfo" -delete

# Rebuild
pnpm build
  2. Check TypeScript version: 
    pnpm list typescript
# Should be 5.3.3 across all packages
  3. Reinstall dependencies: 
    rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install
Error:
Error: Module not found: Can't resolve '@skyteam/ui'
Solution:
# Build packages first
pnpm --filter @skyteam/ui build
pnpm --filter @skyteam/database build

# Then build Next.js apps
pnpm --filter @skyteam/web build
Turborepo should handle this automatically via ^build dependency, but manual builds help diagnose issues.
Issue: Builds using stale/cached codeSolution:
# Clear Turbo cache
rm -rf .turbo

# Force rebuild without cache
pnpm build --force
Error:
Could not find a valid rojo project file
Solution:
# Ensure you're in the models directory
cd apps/models

# Check for default.project.json
ls -la default.project.json

# Rebuild
pnpm build

​
Dependency Issues

Error:
ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies
Solutions:
  1. Use correct pnpm version: 
    # Check version
pnpm --version
# Should be 10.5.2 or later

# Update pnpm
npm install -g pnpm@latest
  2. Clear pnpm cache: 
    pnpm store prune
rm -rf node_modules
pnpm install
  3. Use legacy peer deps (last resort): 
    # Add to .npmrc
echo "legacy-peer-deps=true" >> .npmrc
pnpm install
Error:
Error: Cannot find module '@skyteam/database'
Solution:
# Verify workspace configuration
cat pnpm-workspace.yaml

# Reinstall to recreate symlinks
rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install

# Build the missing package
pnpm --filter @skyteam/database build
Issue: Multiple versions of the same package installedSolution:
# Check for duplicate packages
pnpm list <package-name>

# Deduplicate
pnpm dedupe

# If issues persist, use overrides in root package.json
{
  "pnpm": {
    "overrides": {
      "typescript": "^5.3.3"
    }
  }
}

​
Development Server Issues

Issue: Changes don’t reflect in browserSolutions:
  1. For Next.js apps: 
    # Clear .next cache
rm -rf apps/web/.next
pnpm --filter @skyteam/web dev
  2. For shared packages: 
    # Run package in watch mode
pnpm --filter @skyteam/ui dev
  3. Hard reload browser:
    • Chrome: Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows/Linux)
    • Clear browser cache
Issue: Accidentally started multiple dev serversSolution:
# Kill all Node processes
pkill -f node

# Or kill specific processes
lsof -i :3000  # web
lsof -i :4000  # api
kill -9 <PID>
Issue: process.env.X is undefinedSolutions:
  1. Verify .env exists: 
    ls -la .env
cat .env
  2. Restart dev server: 
    # Stop server (Ctrl+C)
# Start again
pnpm dev
  3. For Next.js public vars:
    • Must start with NEXT_PUBLIC_
    • Example: NEXT_PUBLIC_API_URL
  4. For Turbo global env:
    • Check turbo.json globalEnv array
    • Add your variable if missing

​
ROBLOX Integration Issues

Issue: ROBLOX Studio can’t connect to Rojo serverSolutions:
  1. Verify Rojo is running: 
    pnpm --filter @skyteam/models dev:serve
# Should show: Rojo server listening on port 34872
  2. Check Rojo plugin:
    • Open ROBLOX Studio
    • Go to Plugins tab
    • Click “Rojo” plugin
    • Enter port: 34872
    • Click “Connect”
  3. Firewall issues:
    • Allow ROBLOX Studio through firewall
    • Allow Node.js through firewall
Error:
Diagnostic Error: Type 'X' is not compatible with Roblox-ts
Solution:
  1. Use Roblox-ts types: 
    // Don't use DOM types
// Use @rbxts/types instead
import { Players } from "@rbxts/services";
  2. Check tsconfig.json: 
    {
  "compilerOptions": {
    "types": ["@rbxts/types"],
    "typeRoots": ["node_modules/@rbxts"]
  }
}
  3. Rebuild: 
    cd apps/models
rm -rf out
pnpm build

​
Getting More Help

If you’re still experiencing issues:
  1. Check logs: Review console output for detailed error messages
  2. Enable debug mode: Set DEBUG=* in your environment
  3. Search issues: Check the GitHub repository issues
  4. Ask for help: Open a new issue with:
    • Error message
    • Steps to reproduce
    • Environment info (node --version, pnpm --version)
    • Relevant logs
When sharing logs or errors, make sure to remove sensitive information like API keys, tokens, and database credentials.

Build docs developers (and LLMs) love

Get started for freeTalk to us