Skip to content

troubleshooting.md

Latest commit

 

History

History
383 lines (296 loc) · 7.6 KB

troubleshooting.md

File metadata and controls

383 lines (296 loc) · 7.6 KB

Troubleshooting Guide

Common issues and solutions for @dreamfactory/create.

Setup Issues

Docker Not Installed

Error: Docker is not installed or not running

Solution:

  1. Install Docker: https://docs.docker.com/get-docker/
  2. Start Docker Desktop (Mac/Windows) or Docker daemon (Linux)
  3. Verify: docker ps

Port Already in Use

Error: Port 8080 is already allocated

Solution:

  1. Find what's using the port:

    sudo lsof -i :8080
# or
sudo netstat -tlnp | grep 8080

  2. Option A: Stop the conflicting service

    # If it's another DreamFactory instance:
cd other-project && docker compose down

  3. Option B: Use a different port

    npx @dreamfactory/create my-project --port 8081

Build Fails - Out of Memory

Error: JavaScript heap out of memory

Solution: Increase Docker memory allocation:

  • Docker Desktop: Settings → Resources → Memory → 4GB+
  • Restart Docker Desktop

Containers Won't Start

Error: Service 'web' failed to start

Solution:

  1. Check logs:

    cd my-project
docker compose logs web

  2. Common causes:

    • Port conflict (see above)
    • Insufficient disk space: df -h
    • PostgreSQL not ready: Wait 30s and retry

  3. Force rebuild:

    docker compose down -v
docker compose up --build

Connection Issues

Can't Access Admin UI

http://localhost:8080 → Connection refused

Solution:

  1. Verify containers are running:

    docker ps | grep dreamfactory

  2. Check container health:

    docker compose ps
# Should show "healthy" status

  3. Wait for startup: DreamFactory takes 1-2 minutes to fully initialize

    docker compose logs -f web | grep "nginx"
# Wait for: "nginx started"

  4. Check firewall:

    curl -v http://localhost:8080/api/v2/system/environment

Database Connection Failed

Error: SQLSTATE[08006] connection refused

Solution:

  1. Verify database container is running:

    docker ps | grep postgres

  2. Check database credentials:

    • Review .env file
    • Ensure DB_PASSWORD matches between DreamFactory and database

  3. For external databases:

    • Verify network connectivity: ping db.example.com
    • Check firewall rules
    • For localhost: Use host.docker.internal (Mac/Windows) or 172.17.0.1 (Linux)

  4. Test direct connection:

    docker exec -it my-project-postgres-1 psql -U dreamfactory -d dreamfactory

MCP / Claude Integration Issues

Claude Desktop Can't Connect

MCP server "dreamfactory-demo" failed to start

Solution:

  1. Verify MCP config location:

    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json
    • Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. Check config syntax:

    cat ~/.config/Claude/claude_desktop_config.json | jq
# Should parse without errors

  3. Verify DreamFactory is running:

    curl http://localhost:8080/api/v2/system/environment

  4. Check API key:

    # Test API key from config:
curl -H "X-DreamFactory-API-Key: YOUR_KEY" \
  http://localhost:8080/api/v2/demo_db/_table

  5. Restart Claude Desktop:

    • Completely quit Claude Desktop
    • Wait 5 seconds
    • Restart

MCP Tools Not Working

Claude says: "I don't have access to database tools"

Solution:

  1. Check MCP server status in Claude:

    • Start new chat
    • Type: /mcp
    • Verify dreamfactory-demo appears and is connected

  2. Verify OAuth flow:

    # Check MCP daemon logs:
docker compose logs web | grep "MCP"

  3. Regenerate OAuth client:

    • Admin UI → Apps → Your App → Edit
    • Delete and recreate OAuth client
    • Update .mcp.json with new client ID/secret

  4. Test MCP endpoint directly:

    curl -X POST http://localhost:8080/api/v2/mcp/demo_db \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

"fetch failed" Errors

Error: fetch failed (ECONNREFUSED)

Solution: This was a bug in early versions, fixed in v0.1.0+.

  1. Update to latest version:

    npx @dreamfactory/create@latest my-new-project

  2. If using existing project:

    • The Dockerfile includes a fix for containerized port mapping
    • Rebuild: docker compose down && docker compose up --build

API Issues

401 Unauthorized

{"error": {"code": 401, "message": "Unauthorized"}}

Solution:

  1. Check API key:

    # Verify key in .env matches your request:
cat .env | grep DREAMFACTORY_API_KEY

  2. Generate new API key:

    • Admin UI → Apps → Create new app
    • Copy API key
    • Update .env and MCP configs

403 Forbidden

{"error": {"code": 403, "message": "Access Denied"}}

Solution: RBAC is blocking your request.

  1. Check role configuration:

    • Admin UI → Roles → Your role
    • Verify service access is configured
    • Check HTTP method is allowed (GET/POST/etc.)

  2. Check field restrictions:

    • Review "Deny Fields" list
    • Verify field names match exactly (case-sensitive)

  3. Test with admin credentials:

    # Login as admin first to verify API works:
curl -X POST http://localhost:8080/api/v2/user/session \
  -d '{"email":"admin@example.com","password":"YOUR_PASSWORD"}'

Empty Results (No Errors)

{"resource": []}

Solution:

  1. RBAC filter too restrictive:

    • Check role filter configuration
    • Test without filters first

  2. Wrong table name:

    # List all tables:
curl http://localhost:8080/api/v2/demo_db/_table

  3. Database actually empty:

    # Check row count:
docker exec -it my-project-demo_db-1 \
  psql -U postgres -d pagila -c "SELECT COUNT(*) FROM customer;"

Performance Issues

Slow API Responses

Requests taking > 5 seconds

Solution:

  1. Check Docker resources:

    • Increase CPU/Memory in Docker Desktop settings
    • Recommended: 4GB RAM, 2+ CPUs

  2. Database optimization:

    • Add indexes to frequently queried columns
    • Review slow query logs

  3. Enable caching:

    # docker-compose.yml already includes Redis
# Verify CACHE_DRIVER=redis in .env

  4. Check network:

    # If using external database, test latency:
ping db.example.com

General Debugging

View All Logs

cd my-project

# All services:
docker compose logs -f

# Specific service:
docker compose logs -f web

# Last 100 lines:
docker compose logs --tail 100 web

# Follow new logs:
docker compose logs -f --tail 0 web

Restart Everything

docker compose restart

Complete Reset

# WARNING: Deletes all data and volumes
docker compose down -v
rm -rf my-project
npx @dreamfactory/create my-project

Check System Environment

# Verify DreamFactory version and status:
curl http://localhost:8080/api/v2/system/environment | jq

Still Having Issues?

  1. Check existing issues: https://github.com/dreamfactorysoftware/create-dreamfactory/issues

  2. Create new issue: Include:

    • Operating system
    • Docker version: docker --version
    • Error logs: docker compose logs web
    • Steps to reproduce

  3. Community forum: https://community.dreamfactory.com

  4. Commercial support: https://www.dreamfactory.com/support