Fix Direct I/O in Workflow Functions

Overview

This skill helps diagnose and fix a critical error pattern where I/O operations (HTTP calls, database queries, file operations) are performed directly in workflow functions instead of in steps. This violates Temporal's determinism requirements.

When to Use This Skill

You're seeing:

•Workflow hangs indefinitely
•Undefined or empty responses
•"workflow must be deterministic" errors
•Network operations failing silently
•Timeouts without clear cause

Root Cause

Workflow functions must be deterministic - they should only orchestrate steps, not perform I/O directly. When you make HTTP calls, database queries, or any external operations directly in a workflow function:

•Hangs: The workflow may hang because I/O isn't properly handled
•Determinism violations: Temporal replays workflows, and I/O results differ
•No retry logic: Direct calls bypass Output SDK's retry mechanisms
•No tracing: Operations aren't recorded in the workflow trace

Symptoms

Direct fetch/axios in Workflow

typescript

// WRONG: I/O directly in workflow
export default workflow({
  fn: async (input) => {
    const response = await fetch('https://api.example.com/data');  // BAD!
    const data = await response.json();
    return { data };
  }
});

Direct Database Calls

typescript

// WRONG: Database I/O in workflow
export default workflow({
  fn: async (input) => {
    const user = await db.users.findById(input.userId);  // BAD!
    return { user };
  }
});

File System Operations

typescript

// WRONG: File I/O in workflow
import fs from 'fs/promises';

export default workflow({
  fn: async (input) => {
    const data = await fs.readFile(input.path, 'utf-8');  // BAD!
    return { data };
  }
});

Solution

Move ALL I/O operations to step functions. Steps are designed to handle non-deterministic operations.

Before (Wrong)

typescript

export default workflow({
  fn: async (input) => {
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();
    return { data };
  }
});

After (Correct)

typescript

import { z, step, workflow } from '@outputai/core';
import { httpClient } from '@outputai/http';

// Create a step for the I/O operation
export const fetchData = step({
  name: 'fetchData',
  inputSchema: z.object({
    endpoint: z.string(),
  }),
  outputSchema: z.object({
    data: z.unknown(),
  }),
  fn: async (input) => {
    const client = httpClient({ prefixUrl: 'https://api.example.com' });
    const data = await client.get(input.endpoint).json();
    return { data };
  },
});

// Workflow only orchestrates steps
export default workflow({
  inputSchema: z.object({}),
  outputSchema: z.object({ data: z.unknown() }),
  fn: async (input) => {
    const result = await fetchData({ endpoint: 'data' });
    return result;
  },
});

Complete Example: Database Operation

Before (Wrong)

typescript

export default workflow({
  fn: async (input) => {
    const user = await prisma.user.findUnique({
      where: { id: input.userId }
    });
    const orders = await prisma.order.findMany({
      where: { userId: input.userId }
    });
    return { user, orders };
  }
});

After (Correct)

typescript

import { z, step, workflow } from '@outputai/core';
import { prisma } from '../lib/db';

export const fetchUser = step({
  name: 'fetchUser',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({
    user: z.object({
      id: z.string(),
      name: z.string(),
      email: z.string(),
    }).nullable(),
  }),
  fn: async (input) => {
    const user = await prisma.user.findUnique({
      where: { id: input.userId }
    });
    return { user };
  },
});

export const fetchOrders = step({
  name: 'fetchOrders',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({
    orders: z.array(z.object({
      id: z.string(),
      total: z.number(),
    })),
  }),
  fn: async (input) => {
    const orders = await prisma.order.findMany({
      where: { userId: input.userId }
    });
    return { orders };
  },
});

export default workflow({
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({
    user: z.unknown(),
    orders: z.array(z.unknown()),
  }),
  fn: async (input) => {
    const { user } = await fetchUser({ userId: input.userId });
    const { orders } = await fetchOrders({ userId: input.userId });
    return { user, orders };
  },
});

Finding Direct I/O in Workflows

Search for common I/O patterns in workflow files:

bash

# Find fetch calls
grep -rn "await fetch" src/workflows/

# Find axios calls
grep -rn "axios\." src/workflows/

# Find database operations
grep -rn "prisma\.\|db\.\|mongoose\." src/workflows/

# Find file system operations
grep -rn "fs\.\|readFile\|writeFile" src/workflows/

Then review each match to see if it's in a workflow function vs a step function.

What CAN Be in Workflow Functions

Workflow functions should contain:

•Step calls: await myStep(input)
•Orchestration logic: conditionals, loops (over step calls)
•Data transformation: Pure functions on step results
•Constants: Static values and configuration

Workflow functions should NOT contain:

•HTTP/API calls
•Database operations
•File system operations
•External service calls
•Anything that talks to the network or filesystem

Verification

After moving I/O to steps:

•Run the workflow: npx output workflow run <name> '<input>'
•Check the trace: npx output workflow debug <id> --format json
•Verify steps appear: Look for your I/O steps in the trace
•Confirm no errors: No determinism warnings or hangs

Benefits of Steps for I/O

•Retry logic: Steps can be retried on failure
•Tracing: I/O operations appear in workflow traces
•Timeouts: Steps can have individual timeouts
•Determinism: Replays use recorded results
•Debugging: Clear visibility into what happened

Related Issues

•For HTTP client best practices, see output-error-http-client
•For non-determinism from other causes, see output-error-nondeterminism