Common issues and solutions for the Yemaya platform.
Table of Contents#
- Installation Issues
- Database Issues
- Authentication Issues
- API Issues
- AI Generation Issues
- 3D Generation Issues
- GPU Jobs Issues
- Engine Integration Issues
- Performance Issues
- Debugging Tools
Installation Issues#
pnpm install fails#
Symptom: Installation fails with dependency errors.
Solutions:
-
Clear cache and reinstall:
bashrm -rf node_modules pnpm-lock.yaml pnpm store prune pnpm install -
Check Node.js version:
bashnode --version # Should be 20+ pnpm --version # Should be 9+ -
If using Windows, enable long paths:
powershellgit config --system core.longpaths true
Docker services won't start#
Symptom: docker compose up -d fails.
Solutions:
-
Check Docker is running:
bashdocker info -
Check port conflicts:
bash# Check if ports are in use lsof -i :5432 # PostgreSQL lsof -i :6379 # Redis lsof -i :9000 # MinIO -
Reset Docker volumes:
bashdocker compose down -v docker compose up -d
Build fails with TypeScript errors#
Symptom: pnpm build shows type errors.
Solutions:
-
Rebuild all packages:
bashpnpm clean pnpm build -
Generate Prisma client:
bashpnpm --filter @yemaya/database db:generate -
Clear TypeScript cache:
bashrm -rf packages/*/dist rm -rf packages/*/.turbo pnpm build
Database Issues#
"Connection refused" to PostgreSQL#
Symptom: Error: connect ECONNREFUSED 127.0.0.1:5432
Solutions:
-
Check PostgreSQL is running:
bashdocker compose ps postgres # Should show "Up" status -
Verify connection string:
bashecho $DATABASE_URL # Should match docker-compose.yml settings -
Test connection manually:
bashdocker compose exec postgres psql -U yemaya -d yemaya -c "SELECT 1" -
If using custom PostgreSQL, ensure:
pg_hba.confallows connections- User has correct permissions
- Database exists
Migration fails#
Symptom: pnpm db:migrate shows errors.
Solutions:
-
Reset database (development only):
bashpnpm --filter @yemaya/database db:reset -
Check migration status:
bashpnpm --filter @yemaya/database prisma migrate status -
For specific migration errors, check:
bash# View migration SQL pnpm --filter @yemaya/database prisma migrate diff
Redis connection issues#
Symptom: Error: Redis connection to localhost:6379 failed
Solutions:
-
Check Redis is running:
bashdocker compose ps redis redis-cli ping # Should return "PONG" -
Check Redis URL:
bashecho $REDIS_URL # Should be redis://localhost:6379 -
Test Redis connection:
bashredis-cli > SET test "hello" > GET test
Authentication Issues#
JWT token expired#
Symptom: 401 Unauthorized with "Token expired" message.
Solutions:
-
Use refresh token endpoint:
bashcurl -X POST http://localhost:3000/api/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{"refreshToken": "your_refresh_token"}' -
If refresh token also expired, re-authenticate:
bashcurl -X POST http://localhost:3000/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email": "...", "password": "..."}'
OAuth callback fails#
Symptom: OAuth redirects to error page.
Solutions:
-
Check OAuth credentials in
.env:bashecho $GOOGLE_CLIENT_ID echo $GOOGLE_CLIENT_SECRET -
Verify callback URL matches provider settings:
- Google:
http://localhost:3000/api/v1/auth/oauth/google/callback - GitHub:
http://localhost:3000/api/v1/auth/oauth/github/callback
- Google:
-
Check browser console for specific errors.
"Invalid credentials"#
Symptom: Login fails with valid-looking credentials.
Solutions:
-
Check account exists and is verified:
bash# Using Prisma Studio pnpm --filter @yemaya/database db:studio # Find user in User table -
Check for account lockout (5 failed attempts):
- Wait 15 minutes, or
- Reset via admin API/database
-
Reset password:
bashcurl -X POST http://localhost:3000/api/v1/auth/password/reset \ -H "Content-Type: application/json" \ -d '{"email": "your@email.com"}'
API Issues#
429 Too Many Requests#
Symptom: Rate limit exceeded.
Solutions:
-
Wait for rate limit window to reset (check
X-RateLimit-Resetheader) -
Implement request throttling:
typescript// Simple throttle const delay = (ms) => new Promise((r) => setTimeout(r, ms)); await delay(1000); // Wait 1 second between requests -
For production, upgrade tier or request limit increase.
CORS errors#
Symptom: "Access-Control-Allow-Origin" errors in browser.
Solutions:
-
Check CORS configuration in
.env:bashCORS_ORIGINS=http://localhost:5173,http://localhost:3000 -
For development, ensure frontend URL is in allowed origins.
-
Check request is using correct protocol (http vs https).
Request body too large#
Symptom: 413 Payload Too Large
Solutions:
-
Check file size limits in config.
-
Use multipart upload for large files:
bash# Get upload URL curl -X POST http://localhost:3000/api/v1/assets \ -H "Authorization: Bearer $TOKEN" \ -d '{"filename": "large-file.zip", "size": 500000000}' # Upload to presigned URL curl -X PUT "$PRESIGNED_URL" --data-binary @large-file.zip
Validation errors#
Symptom: 400 Bad Request with validation details.
Solutions:
-
Check the error response for specific field errors:
json{ "error": { "code": "VALIDATION_ERROR", "details": [{ "field": "email", "message": "Invalid email format" }] } } -
Refer to API documentation for correct schema.
-
Use SDK types for type-safe requests:
typescriptimport { YemayaClient } from '@yemaya/sdk'; const client = new YemayaClient({ apiKey: '...' }); // TypeScript will catch schema errors
AI Generation Issues#
API key errors#
Symptom: "Invalid API key" or "Unauthorized" from AI providers.
Solutions:
-
Verify API key is set:
bashecho $ANTHROPIC_API_KEY echo $OPENAI_API_KEY -
Check key has correct permissions/quota.
-
Test key directly:
bash# Test Anthropic curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model": "claude-3-haiku-20240307", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'
Generation timeout#
Symptom: Request times out waiting for AI response.
Solutions:
-
Use async endpoint for long generations:
bash# Async (returns job ID immediately) POST /ai/text # Then poll for result GET /ai/jobs/{jobId} -
Reduce
maxTokensfor faster responses. -
Check provider status pages for outages.
Cost exceeded#
Symptom: "Budget exceeded" error.
Solutions:
-
Check current usage:
bashcurl http://localhost:3000/api/v1/ai/usage \ -H "Authorization: Bearer $TOKEN" -
Increase budget limits in config or admin panel.
-
Use cheaper models for development:
json{"model": "claude-3-haiku-20240307"} // Cheapest Claude {"model": "gpt-3.5-turbo"} // Cheapest OpenAI
3D Generation Issues#
Generation failed#
Symptom: 3D generation job fails.
Solutions:
-
Check job status and error:
bashcurl http://localhost:3000/api/v1/3d/jobs/{jobId} \ -H "Authorization: Bearer $TOKEN" -
Common causes:
- Invalid prompt (too vague or complex)
- Provider rate limit
- Provider temporary outage
-
Retry with modified parameters:
json{ "prompt": "simple wooden chair", // More specific "quality": "standard", // Lower quality for testing "provider": "meshy" // Try different provider }
Poor model quality#
Symptom: Generated 3D model has artifacts or poor topology.
Solutions:
-
Use post-processing:
bashcurl -X POST http://localhost:3000/api/v1/3d/process/optimize \ -H "Authorization: Bearer $TOKEN" \ -d '{"modelUrl": "...", "targetPolyCount": 10000}' -
Try higher quality setting (slower, more expensive):
json{ "quality": "high" } -
Use image-to-3D with reference images for better results.
Texture issues#
Symptom: Missing or low-quality textures.
Solutions:
-
Enable texture upscaling:
json{ "textureResolution": 2048, "upscaleTextures": true } -
Re-bake textures:
bashcurl -X POST http://localhost:3000/api/v1/3d/process/bake-textures \ -H "Authorization: Bearer $TOKEN" \ -d '{"modelUrl": "...", "resolution": 4096}'
GPU Jobs Issues#
Job stuck in queue#
Symptom: Job remains in "queued" status.
Solutions:
-
Check provider health:
bashcurl http://localhost:3000/api/v1/gpu-jobs/health \ -H "Authorization: Bearer $TOKEN" -
Check circuit breaker status:
bashcurl http://localhost:3000/api/v1/gpu-jobs/circuit-breakers \ -H "Authorization: Bearer $TOKEN" -
Reset circuit breaker if open:
bashcurl -X POST http://localhost:3000/api/v1/gpu-jobs/circuit-breakers/runpod-serverless/reset \ -H "Authorization: Bearer $TOKEN"
Job failed repeatedly#
Symptom: Job in DLQ after multiple failures.
Solutions:
-
Check DLQ entry for error details:
bashcurl http://localhost:3000/api/v1/gpu-jobs/dlq/{entryId} \ -H "Authorization: Bearer $TOKEN" -
Common failure reasons:
max_retries_exceeded: Underlying issue not resolvedbudget_exceeded: Cost limit hittimeout_exceeded: Job taking too long
-
Replay with modified parameters:
bashcurl -X POST http://localhost:3000/api/v1/gpu-jobs/dlq/{entryId}/replay \ -H "Authorization: Bearer $TOKEN" \ -d '{"preferredProvider": "modal", "modifyParameters": {"quality": "standard"}}'
Provider unavailable#
Symptom: "No providers available" error.
Solutions:
-
Check provider API keys are configured.
-
Verify provider status:
- RunPod: https://status.runpod.io
- Modal: https://status.modal.com
- AWS: https://health.aws.amazon.com
-
Check routing rules aren't excluding all providers.
Engine Integration Issues#
Blender won't connect#
Symptom: "Connection refused" to Blender.
Solutions:
-
Ensure Blender addon is installed and enabled:
- Blender > Edit > Preferences > Add-ons
- Search "Yemaya" and enable
-
Start the WebSocket server in Blender:
- Blender > Yemaya > Start Server
-
Check port (default 9999):
bashcurl http://localhost:9999/health
Godot plugin errors#
Symptom: GDExtension not loading.
Solutions:
-
Rebuild the extension:
bashcd packages/godot pnpm build:gdextension -
Check Godot version compatibility (4.2+ required).
-
Copy extension files to Godot project's
addons/folder.
Unreal plugin crash#
Symptom: Unreal crashes when loading plugin.
Solutions:
-
Check UE version compatibility (5.3+ required).
-
Rebuild plugin for correct engine version.
-
Check logs:
- Windows:
%LOCALAPPDATA%\UnrealEngine\<version>\Saved\Logs - Mac:
~/Library/Logs/Unreal Engine/
- Windows:
Performance Issues#
Slow API responses#
Symptom: API calls taking >1 second.
Solutions:
-
Enable response caching:
bash# Check Redis is running redis-cli ping -
Check database query performance:
bash# Enable query logging DEBUG=prisma:query pnpm dev -
Profile slow endpoints:
bashcurl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/api/v1/...
High memory usage#
Symptom: Node.js process using excessive memory.
Solutions:
-
Check for memory leaks:
bashnode --inspect apps/api/dist/index.js # Use Chrome DevTools Memory profiler -
Increase Node.js memory limit:
bashNODE_OPTIONS="--max-old-space-size=4096" pnpm start -
Check for large file operations holding memory.
Database connection exhaustion#
Symptom: "Too many connections" error.
Solutions:
-
Check connection pool settings:
typescript// In DATABASE_URL postgresql://user:pass@host/db?connection_limit=20 -
Use PgBouncer for connection pooling in production.
-
Check for connection leaks (unclosed transactions).
Debugging Tools#
Enable debug logging#
# All debug logs
DEBUG=* pnpm dev
# Specific modules
DEBUG=yemaya:* pnpm dev
DEBUG=prisma:query pnpm dev
DEBUG=gpu-jobs:* pnpm dev
API request tracing#
# Enable OpenTelemetry tracing
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 pnpm dev
# View traces in Jaeger/Zipkin
open http://localhost:16686
Database query analysis#
# Prisma Studio for data inspection
pnpm --filter @yemaya/database db:studio
# PostgreSQL EXPLAIN ANALYZE
docker compose exec postgres psql -U yemaya -c "EXPLAIN ANALYZE SELECT ..."
Redis inspection#
# Monitor all commands
redis-cli MONITOR
# Check memory usage
redis-cli INFO memory
# List all keys (careful in production!)
redis-cli KEYS "*"
Health check script#
#!/bin/bash
# health-check.sh
echo "Checking services..."
# API
curl -s http://localhost:3000/health && echo "API: OK" || echo "API: FAILED"
# PostgreSQL
docker compose exec -T postgres pg_isready && echo "PostgreSQL: OK" || echo "PostgreSQL: FAILED"
# Redis
redis-cli ping > /dev/null && echo "Redis: OK" || echo "Redis: FAILED"
# MinIO
curl -s http://localhost:9000/minio/health/live && echo "MinIO: OK" || echo "MinIO: FAILED"
Getting More Help#
If you can't resolve an issue:
- Search existing issues: https://github.com/yemaya/yemaya/issues
- Ask on Discord: https://discord.gg/yemaya
- Create detailed bug report with:
- Steps to reproduce
- Environment details
- Error messages/logs
- What you've tried