Troubleshooting

Troubleshooting

This guide covers common issues you might encounter with Bifrost.

Workflow Not Discovered

Symptom: Workflow doesn’t appear in UI or API

Check 1: Decorator Applied

# ✅ Correct
from bifrost import workflow

@workflow
async def my_workflow(name: str):
    """Do something useful."""
    return {"success": True}

# ❌ Wrong: No decorator
async def my_workflow(name: str):
    pass

# ❌ Wrong: Not async
@workflow
def my_workflow(name: str):  # Should be async def
    pass

Check 2: Filename Rules

✅ my_workflow.py              (discovered)
✅ user_onboarding.py          (discovered)

❌ _my_workflow.py             (ignored, starts with _)
❌ my_workflow (no .py)        (ignored)

Check 3: Check API Logs

docker compose logs api | grep -i error
docker compose logs api | grep -i import

Look for syntax errors or import failures.

Workflow Execution Fails

Symptom: Workflow executes but returns error

Check Error Message

Common errors and fixes:

❌ "TypeError: missing required argument"
   Fix: Form didn't pass all required parameters

❌ "ImportError: cannot import name..."
   Fix: Check your imports are correct

❌ "asyncio.TimeoutError"
   Fix: Increase timeout_seconds in @workflow decorator

Use Proper Error Handling

from bifrost import workflow
import logging

logger = logging.getLogger(__name__)

@workflow
async def my_workflow(email: str):
    """Example with error handling."""
    try:
        result = await some_api_call(email)
        return {"success": True, "data": result}
    except Exception as e:
        logger.error(f"API call failed: {e}")
        return {"success": False, "error": str(e)}

Timeout Issues

Symptom: “Execution timeout” or “asyncio.TimeoutError”

Increase Timeout

@workflow(timeout_seconds=1800)  # 30 minutes
async def long_running_task():
    """Takes a while to complete."""
    pass

Optimize with Parallel Execution

import asyncio

@workflow
async def import_users(users: list):
    """Import users in parallel."""
    # ❌ Slow: One at a time
    # for user in users:
    #     await create_user(user)

    # ✅ Fast: Parallel
    tasks = [create_user(user) for user in users]
    await asyncio.gather(*tasks)

Data Provider Issues

Symptom: Dropdown in form is empty

Check Return Format

from bifrost import data_provider

# ✅ Correct format
@data_provider(name="get_departments", description="List departments")
async def get_departments():
    return [
        {"label": "Engineering", "value": "eng"},
        {"label": "Sales", "value": "sales"}
    ]

# ❌ Wrong: Not list of dicts
@data_provider(name="get_departments", description="List departments")
async def get_departments():
    return ["Engineering", "Sales"]  # Missing label/value

Check for Exceptions

Data providers that throw exceptions will return empty results. Add logging:

@data_provider(name="get_users", description="List users")
async def get_users():
    try:
        users = await fetch_users()
        return [{"label": u["name"], "value": u["id"]} for u in users]
    except Exception as e:
        logger.error(f"Failed to fetch users: {e}")
        return []

Service Health

Check All Services Running

docker compose ps

All services should show “Up” status.

Check API Health

curl http://localhost:3000/api/health

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api
docker compose logs -f worker

Port Conflicts

Check if ports are in use:

lsof -i :3000   # Client
lsof -i :5432   # PostgreSQL
lsof -i :5672   # RabbitMQ
lsof -i :6379   # Redis
lsof -i :9000   # MinIO

Fresh Start

If things are really broken, reset everything:

docker compose down -v  # Remove volumes
docker compose up       # Start fresh

This will delete all data and start with a clean database.

Getting Help

• GitHub Issues: github.com/jackmusick/bifrost/issues
• Execution Logs: Workflows page → Execution History → Click execution
• Add Logging: Use Python’s logging module throughout your workflows