Implementing the Saga Pattern with Spring Boot 4 and Temporal

In a monolithic architecture, maintaining business data consistency is straightforward: developers wrap multiple database operations inside a single @Transactional boundary, and the underlying relational database management system guarantees ACID compliance (Atomicity, Consistency, Isolation, and Durability). If any step in the transaction fails or throws an unhandled runtime exception, the database immediately rolls back all preceding changes to their original state.

In a modern microservices architecture, this monolithic luxury disappears. To achieve domain autonomy and independent team velocity, systems adopt the Database-per-Service pattern. An e-commerce checkout process now spans multiple distributed boundaries: an OrderService records the customer order, a PaymentService charges the credit card, and an InventoryService reserves product warehouse stock. Because each service manages its own isolated database schema, you cannot execute a distributed database transaction across three separate network nodes without catastrophic locking overhead. How do you maintain data consistency if the inventory reservation fails after the customer’s payment has already been captured?

The architectural answer is the Saga Pattern. In this comprehensive technical guide, you will learn how the Saga Pattern solves distributed transaction management, explore the critical architectural differences between Choreography and Orchestration, and implement a production-ready Saga Orchestration workflow using Spring Boot 4, Java 25, and Temporal.

The Fall of Two-Phase Commit in Microservices

Before exploring Sagas, we must understand why traditional distributed transaction protocols fail in modern cloud environments. For decades, distributed systems relied on the Two-Phase Commit (2PC) protocol, often formalized through the X/Open XA standard. In 2PC, a central transaction coordinator communicates with multiple resource managers across two distinct phases:

1. Prepare Phase: The coordinator instructs every participant to acquire local locks on database rows, verify constraints, and write transaction logs to disk. Each node responds with a promise that it is ready to commit.
2. Commit Phase: If all participants respond affirmatively, the coordinator broadcasts a commit command. If any single node fails or votes against the commit, the coordinator broadcasts an abort command to roll back all participants.

While 2PC provides strict serializability, it introduces fatal architectural flaws in distributed cloud systems:

• Blocking Protocol and Lock Contention: Database rows remain locked from the start of the prepare phase until the final commit message is acknowledged. If network latency increases or a participant hangs, records remain locked across services, causing thread pool exhaustion and catastrophic cascading failures.
• Coordinator as a Single Point of Failure: If the central coordinator crashes during the commit phase, participants remain in an uncertain state, unable to release local locks without administrative intervention.
• CAP Theorem Incompatibility: According to the CAP theorem, distributed systems operating over partitioned networks must choose between Consistency and Availability. 2PC prioritizes strict consistency, sacrificing system availability during network hiccups.

Modern distributed systems reject 2PC in favor of Eventual Consistency. This is where the Saga Pattern becomes essential.

What Is the Saga Pattern?

Originally described in a 1987 academic paper by Hector Garcia-Molina and Kenneth Salem, a Saga is a design pattern that structures a distributed business process as a sequence of discrete local transactions. Each local transaction updates the database inside a single microservice and emits a signal to trigger the next transaction in the sequence.

Because each step commits its local database transaction immediately, no long-lived global database locks are held. Services remain responsive, isolation boundaries are respected, and system throughput remains high.

Forward vs. Compensating Transactions

What happens when a step fails mid-flight? Unlike an ACID database transaction, a Saga cannot execute an automatic physical rollback because earlier local transactions have already committed and made their updates visible to other concurrent users.

Instead, a Saga relies on Compensating Transactions. A compensating transaction is an explicit business operation that semantically undoes the effect of a preceding local transaction:

For example:

• If the forward transaction is processPayment(), the compensating transaction is refundPayment().
• If the forward transaction is reserveInventory(), the compensating transaction is releaseInventory().
• If the forward transaction is createOrder(), the compensating transaction is cancelOrder().

In Saga terminology, transactions are categorized into three distinct roles:

1. Compensatable Transactions: Transactions that precede the pivot point and can be semantically undone by a compensating transaction (e.g., payment capture, stock reservation).
2. Pivot Transaction: The point of no return in the workflow. Once the pivot transaction commits successfully, the Saga is guaranteed to proceed to completion.
3. Retriable Transactions: Transactions following the pivot point that cannot fail due to business rules and are guaranteed to succeed eventually through retries (e.g., generating an invoice PDF, dispatching a shipment notification).

Choreography vs. Orchestration: Architectural Trade-Offs

There are two primary paradigms for coordinating a Saga across microservices: Choreography and Orchestration.

1. Saga Choreography (Decentralized Event Streaming)

In Choreography, there is no central controller. Microservices listen to domain events emitted over a message broker such as Apache Kafka (as explored in our architectural guide on The Transactional Outbox Pattern with Spring Boot 4) and react autonomously:

• OrderService creates an order in PENDING status and publishes OrderCreatedEvent.
• PaymentService consumes OrderCreatedEvent, charges the customer, and publishes PaymentProcessedEvent.
• InventoryService consumes PaymentProcessedEvent, attempts stock allocation, and, if exhausted, publishes InventoryFailedEvent.
• PaymentService consumes InventoryFailedEvent and triggers an account refund.
• OrderService consumes InventoryFailedEvent and sets the order status to CANCELLED.

The Limitations of Choreography: While choreography provides loose coupling for simple 2-step workflows, enterprise systems quickly suffer from “event spaghetti.” Because business logic is scattered across independent message listeners, developers cannot inspect the complete state of a distributed transaction in a single place. Cyclic event dependencies, race conditions during compensations, and distributed debugging nightmares become rampant as service counts grow.

2. Saga Orchestration (Centralized Workflow Coordinator)

In Orchestration, a dedicated coordinator (the Orchestrator) directs all participants. The orchestrator explicitly tells each microservice which action to perform, monitors the result, manages timeouts, and triggers compensations in reverse order if a failure occurs.

The benefits of Orchestration include:

• Single Source of Truth: The entire business workflow, retry logic, and compensation sequence are defined in a single, readable orchestrator class.
• State Observability: Engineering teams can query the exact state of any in-flight transaction at any moment.
• Simplified Microservice Interfaces: Participant microservices do not need to know about downstream services or listen for complex failure events; they simply expose RPC or REST endpoints that execute forward actions and compensating actions.

Why Temporal for Saga Orchestration?

Historically, implementing an orchestrator required custom state machines, relational database tables to track execution states, quartz schedulers for timeouts, and message brokers for asynchronous queues. Maintaining such home-grown orchestrators proved fragile and error-prone.

Temporal revolutionizes distributed orchestration through the Workflow as Code paradigm. Instead of defining workflows in clumsy JSON or XML state machines, you write standard Java code using familiar language constructs (loops, conditions, try-catch blocks). The Temporal server acts as a fault-tolerant backend that manages state persistence, queues, retries, and timers.

Durable Execution and Deterministic Replay

The foundational concept behind Temporal is Durable Execution. In traditional software, if a server crashes, runs out of memory (OOM), or experiences a network partition while running a method, the execution state in memory is wiped out.

In Temporal, every step of your workflow is recorded in an immutable, append-only Event History inside the Temporal Cluster. When a Spring Boot worker pod crashes mid-execution:

1. The Temporal Cluster detects the worker heartbeat failure and reassigns the workflow task to another available worker pod.
2. The replacement worker initializes the workflow code and performs Deterministic Replay: it replays the workflow from line 1.
3. Whenever the workflow code encounters an Activity that has already completed (e.g., processPayment), the Temporal SDK does not execute the activity again. Instead, it reads the previously recorded result from the Event History and returns it instantly.
4. When execution reaches the point of failure (e.g., reserveInventory), the worker seamlessly resumes live execution.

This guarantees that distributed transactions survive server restarts, pod evictions, deployments, and database timeouts without data corruption or duplicate financial charges.

Step-by-Step Implementation with Spring Boot 4 & Java 25

Let us implement an enterprise order fulfillment Saga using Spring Boot 4, Java 25, and the Temporal Java SDK.

Configuring Maven Dependencies

Add the Temporal SDK and test dependencies to your pom.xml:

<dependencies>
    <!-- Spring Boot 4 Web Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Temporal Java SDK -->
    <dependency>
        <groupId>io.temporal</groupId>
        <artifactId>temporal-sdk</artifactId>
        <version>1.24.1</version>
    </dependency>

    <!-- Spring Boot 4 Testing & MockMvc -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc-test</artifactId>
        <scope>test</scope>
    </dependency>

    <!-- Temporal In-Memory Testing Environment -->
    <dependency>
        <groupId>io.temporal</groupId>
        <artifactId>temporal-testing</artifactId>
        <version>1.24.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Step 1: Defining the Activity Interfaces

In Temporal, Activities represent individual units of work that interact with external microservices, databases, or third-party APIs. We define an interface annotated with @ActivityInterface containing both forward and compensating methods:

package com.webcodein.workshop.saga;

import io.temporal.activity.ActivityInterface;
import io.temporal.activity.ActivityMethod;

@ActivityInterface
public interface OrderActivities {

    @ActivityMethod
    void processPayment(String accountId, double amount);

    @ActivityMethod
    void refundPayment(String accountId, double amount);

    @ActivityMethod
    void reserveInventory(String orderId);

    @ActivityMethod
    void releaseInventory(String orderId);
}

Step 2: Implementing Activities and Compensations

Next, implement OrderActivitiesImpl. Notice how the activity implementation uses structured logging and simulates inventory exhaustion when an order ID contains the keyword fail:

package com.webcodein.workshop.saga;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class OrderActivitiesImpl implements OrderActivities {

    private static final Logger log = LoggerFactory.getLogger(OrderActivitiesImpl.class);

    @Override
    public void processPayment(String accountId, double amount) {
        log.info("Processing payment for account {} for amount {}", accountId, amount);
        // Call payment gateway API (e.g. Stripe, PayPal)
    }

    @Override
    public void refundPayment(String accountId, double amount) {
        log.warn("Refunding payment for account {} for amount {}", accountId, amount);
        // Execute compensating refund
    }

    @Override
    public void reserveInventory(String orderId) {
        log.info("Reserving inventory for order {}", orderId);
        if (orderId != null && orderId.contains("fail")) {
            log.error("Inventory reservation failed for order {}: Out of stock!", orderId);
            throw new RuntimeException("Out of stock!");
        }
    }

    @Override
    public void releaseInventory(String orderId) {
        log.warn("Releasing reserved inventory for order {}", orderId);
        // Release reserved stock in warehouse
    }
}

Step 3: Writing the Workflow Orchestrator

The workflow orchestrator contains the Saga logic. Temporal provides a built-in io.temporal.workflow.Saga class that tracks every successful forward step and automatically invokes compensations in reverse order if an exception occurs:

package com.webcodein.workshop.saga;

import io.temporal.activity.ActivityOptions;
import io.temporal.common.RetryOptions;
import io.temporal.workflow.Saga;
import io.temporal.workflow.Workflow;
import org.slf4j.Logger;

import java.time.Duration;

public class OrderFulfillmentWorkflowImpl implements OrderFulfillmentWorkflow {

    private static final Logger log = Workflow.getLogger(OrderFulfillmentWorkflowImpl.class);

    // Configure activity execution timeouts and single-attempt policy for demo
    private final ActivityOptions options = ActivityOptions.newBuilder()
            .setStartToCloseTimeout(Duration.ofSeconds(10))
            .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(1).build())
            .build();

    private final OrderActivities activities = Workflow.newActivityStub(OrderActivities.class, options);

    @Override
    public void fulfillOrder(String orderId, String customerId, double amount) {
        // Configure Saga options: sequential reverse-order compensation
        Saga.Options sagaOptions = new Saga.Options.Builder()
                .setParallelCompensation(false)
                .build();
        Saga saga = new Saga(sagaOptions);

        try {
            log.info("Starting Order Fulfillment Saga for order: {}, customer: {}", orderId, customerId);

            // Step 1: Process Payment
            activities.processPayment(customerId, amount);
            // Register compensation immediately after forward action succeeds
            saga.addCompensation(activities::refundPayment, customerId, amount);

            // Step 2: Reserve Inventory
            activities.reserveInventory(orderId);
            saga.addCompensation(activities::releaseInventory, orderId);

            // Forward actions succeeded - transaction complete
            log.info("Order Fulfillment Saga completed successfully for order: {}", orderId);

        } catch (Exception e) {
            log.error("Order Fulfillment Saga failed for order: {}. Executing compensating transactions...", orderId, e);
            // Execute all registered compensations in reverse order
            saga.compensate();
            throw Workflow.wrap(e);
        }
    }
}

Notice the clean design of this code: there are no distributed lock managers, no complex relational database state tracking tables, and no manual event subscriptions. If reserveInventory throws an exception, Temporal catches it, invokes saga.compensate(), and reliably calls refundPayment.

Step 4: Exposing the REST API Controller

To allow HTTP clients to trigger the Saga orchestrator, implement OrderController:

package com.webcodein.workshop.saga;

import io.temporal.client.WorkflowClient;
import io.temporal.client.WorkflowOptions;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final WorkflowClient workflowClient;

    public OrderController(WorkflowClient workflowClient) {
        this.workflowClient = workflowClient;
    }

    @PostMapping
    public ResponseEntity<Map<String, Object>> submitOrder(@RequestBody CreateOrderRequest request) {
        if (request == null || request.orderId() == null || request.customerId() == null || request.amount() <= 0) {
            return ResponseEntity.badRequest().body(Map.of(
                    "status", "FAILED",
                    "message", "Invalid order payload: orderId, customerId, and positive amount are required."
            ));
        }

        String workflowId = "order-saga-" + request.orderId();
        WorkflowOptions options = WorkflowOptions.newBuilder()
                .setWorkflowId(workflowId)
                .setTaskQueue(SagaApplication.TASK_QUEUE)
                .build();

        OrderFulfillmentWorkflow workflow = workflowClient.newWorkflowStub(OrderFulfillmentWorkflow.class, options);

        try {
            workflow.fulfillOrder(request.orderId(), request.customerId(), request.amount());
            return ResponseEntity.ok(Map.of(
                    "status", "SUCCESS",
                    "orderId", request.orderId(),
                    "workflowId", workflowId,
                    "message", "Order fulfilled successfully through Temporal Saga orchestration."
            ));
        } catch (Exception e) {
            return ResponseEntity.status(500).body(Map.of(
                    "status", "COMPENSATED",
                    "orderId", request.orderId(),
                    "workflowId", workflowId,
                    "error", e.getMessage() != null ? e.getMessage() : "Saga failure: compensations executed."
            ));
        }
    }

    public record CreateOrderRequest(String orderId, String customerId, double amount) {}
}

Step 5: Bootstrapping the Spring Boot Worker

In SagaApplication.java, configure the Temporal WorkflowClient bean and bootstrap a worker instance using a Spring Boot CommandLineRunner:

package com.webcodein.workshop.saga;

import io.temporal.client.WorkflowClient;
import io.temporal.serviceclient.WorkflowServiceStubs;
import io.temporal.worker.Worker;
import io.temporal.worker.WorkerFactory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class SagaApplication {

    private static final Logger log = LoggerFactory.getLogger(SagaApplication.class);
    public static final String TASK_QUEUE = "OrderFulfillmentTaskQueue";

    public static void main(String[] args) {
        SpringApplication.run(SagaApplication.class, args);
    }

    @Bean
    public WorkflowClient workflowClient() {
        WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs();
        return WorkflowClient.newInstance(service);
    }

    @Bean
    @ConditionalOnProperty(name = "temporal.worker.enabled", havingValue = "true", matchIfMissing = true)
    public CommandLineRunner startWorker(WorkflowClient client) {
        return args -> {
            if (client == null || client.getOptions() == null) {
                return;
            }
            try {
                WorkerFactory factory = WorkerFactory.newInstance(client);
                Worker worker = factory.newWorker(TASK_QUEUE);

                worker.registerWorkflowImplementationTypes(OrderFulfillmentWorkflowImpl.class);
                worker.registerActivitiesImplementations(new OrderActivitiesImpl());

                factory.start();
                log.info("Temporal Worker started for task queue: {}", TASK_QUEUE);
            } catch (Exception e) {
                log.warn("Could not start Temporal worker: {}", e.getMessage());
            }
        };
    }
}

Testing Strategy: Zero-Cluster In-Memory Testing

Testing distributed workflows has historically been challenging, requiring Docker containers or running infrastructure. Temporal solves this with TestWorkflowEnvironment, which launches an in-memory gRPC server and test workflow engine directly inside the JVM.

Here is how we verify that compensations execute strictly in reverse order when downstream activities fail:

package com.webcodein.workshop.saga;

import io.temporal.client.WorkflowClient;
import io.temporal.client.WorkflowException;
import io.temporal.client.WorkflowOptions;
import io.temporal.testing.TestWorkflowEnvironment;
import io.temporal.worker.Worker;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;

class OrderFulfillmentWorkflowTest {

    private TestWorkflowEnvironment testEnv;
    private Worker worker;
    private WorkflowClient workflowClient;

    @BeforeEach
    public void setUp() {
        testEnv = TestWorkflowEnvironment.newInstance();
        worker = testEnv.newWorker(SagaApplication.TASK_QUEUE);
        worker.registerWorkflowImplementationTypes(OrderFulfillmentWorkflowImpl.class);
        worker.registerActivitiesImplementations(new OrderActivitiesImpl());
        workflowClient = testEnv.getWorkflowClient();
    }

    @AfterEach
    public void tearDown() {
        testEnv.close();
    }

    @Test
    @DisplayName("Happy Path: Order workflow completes successfully when all activities pass")
    void testSuccessfulSaga() {
        testEnv.start();

        OrderFulfillmentWorkflow workflow = workflowClient.newWorkflowStub(OrderFulfillmentWorkflow.class,
                WorkflowOptions.newBuilder().setTaskQueue(SagaApplication.TASK_QUEUE).build());

        workflow.fulfillOrder("order-123", "cust-1", 100.0);
    }

    @Test
    @DisplayName("Compensation Path: Order workflow fails at inventory and wraps exception")
    void testFailedSagaExecutesCompensations() {
        testEnv.start();

        OrderFulfillmentWorkflow workflow = workflowClient.newWorkflowStub(OrderFulfillmentWorkflow.class,
                WorkflowOptions.newBuilder().setTaskQueue(SagaApplication.TASK_QUEUE).build());

        assertThatThrownBy(() -> workflow.fulfillOrder("order-fail-456", "cust-1", 100.0))
                .isInstanceOf(WorkflowException.class);
    }

    @Test
    @DisplayName("Verified Compensation Invariant: Compensating transactions execute in reverse order")
    void testFailedSagaExecutesExactCompensationInReverseOrder() {
        TestWorkflowEnvironment env = TestWorkflowEnvironment.newInstance();
        try {
            TestOrderActivities stub = new TestOrderActivities();

            Worker customWorker = env.newWorker("VerifiedQueue");
            customWorker.registerWorkflowImplementationTypes(OrderFulfillmentWorkflowImpl.class);
            customWorker.registerActivitiesImplementations(stub);

            env.start();

            WorkflowClient client = env.getWorkflowClient();
            OrderFulfillmentWorkflow workflow = client.newWorkflowStub(OrderFulfillmentWorkflow.class,
                    WorkflowOptions.newBuilder().setTaskQueue("VerifiedQueue").build());

            assertThatThrownBy(() -> workflow.fulfillOrder("order-fail-789", "cust-99", 250.0))
                    .isInstanceOf(WorkflowException.class);

            // Strictly verify that forward payment was executed, then compensated, and inventory release was omitted
            assertThat(stub.paymentProcessed).isTrue();
            assertThat(stub.paymentRefunded).isTrue();
            assertThat(stub.inventoryReleased).isFalse();
            assertThat(stub.lastProcessedAccount).isEqualTo("cust-99");
            assertThat(stub.lastProcessedAmount).isEqualTo(250.0);
        } finally {
            env.close();
        }
    }

    static class TestOrderActivities implements OrderActivities {
        boolean paymentProcessed = false;
        boolean paymentRefunded = false;
        boolean inventoryReleased = false;
        String lastProcessedAccount;
        double lastProcessedAmount;

        @Override
        public void processPayment(String accountId, double amount) {
            this.paymentProcessed = true;
            this.lastProcessedAccount = accountId;
            this.lastProcessedAmount = amount;
        }

        @Override
        public void refundPayment(String accountId, double amount) {
            this.paymentRefunded = true;
        }

        @Override
        public void reserveInventory(String orderId) {
            throw new RuntimeException("Simulated inventory failure: Out of stock!");
        }

        @Override
        public void releaseInventory(String orderId) {
            this.inventoryReleased = true;
        }
    }
}

Executing ./mvnw test runs all 11 tests across activities, REST controller, and workflow orchestrations in seconds without external infrastructure.

Architectural Comparison: Temporal vs. Kafka vs. 2PC vs. Outbox

Architects must select the correct coordination mechanism based on isolation requirements, system complexity, and latency tolerances:

Real-World Enterprise Use Cases

1. Multi-Vendor E-Commerce Order Fulfillment

Modern online marketplaces must coordinate payments across payment gateways (Stripe, Adyen), warehouse management systems, courier logistics (FedEx, DHL), and notification channels. If warehouse allocation fails or shipping courier generation rejects an address, the orchestrator refunds the payment and notifies the buyer automatically.

2. Core Banking & Cross-Border Remittances

In financial systems adhering to Clean Architecture & Hexagonal Ports, international wire transfers involve debiting the origin account, validating anti-money laundering (AML) compliance, converting foreign exchange (FX) rates, and crediting the recipient ledger. If the foreign bank network rejects the credit, compensating credits restore customer balances immediately.

3. Travel & Hospitality Booking Engines

Vacation packages bundle flight tickets, hotel rooms, and rental cars. These external third-party partner APIs have disparate latency profiles and non-instant confirmation windows. Temporal Sagas orchestrate long-running asynchronous holds; if the airline rejects the seat confirmation within 24 hours, hotel and car reservations are automatically cancelled.

Production Hardening & Idempotency Guidelines

• Enforce Strict Activity Idempotency: Temporal guarantees at-least-once activity execution. If an activity successfully completes on a remote server but the network acknowledgement drops before reaching the Temporal Cluster, Temporal will retry the activity. Every activity endpoint (e.g., payment charging or database updates) must use idempotency keys (such as an Idempotency-Key header or database unique constraint).
• Adhere to Workflow Determinism: Workflow code must be 100% deterministic to support replay. Never call System.currentTimeMillis(), UUID.randomUUID(), or non-deterministic thread operations directly inside workflow implementations. Always use Workflow.currentTimeMillis() and Workflow.randomUUID(). Combine this with Java 25 Virtual Threads inside Spring Boot workers for scalable asynchronous I/O.
• Configure Bounded Timeouts: Never leave ActivityOptions with default infinite timeouts. Always set setStartToCloseTimeout() and configure explicit backoff policies using RetryOptions to prevent workers from stalling on dead services.

Common Pitfalls & Drop-In Fixes

Pitfall 1: Non-Deterministic Code in Workflow Methods

Symptom: Worker throws io.temporal.worker.NonDeterministicWorkflowException during workflow execution or replay.

Root Cause: Calling non-deterministic system APIs (e.g. new Date(), random numbers, direct database calls) inside a class annotated with @WorkflowInterface.

Fix: Move all I/O, randomness, and clock calls inside @ActivityMethod implementations, or use Temporal’s deterministic wrappers:

// WRONG: Throws NonDeterministicWorkflowException on replay
long now = System.currentTimeMillis();

// CORRECT: Replays identically from Event History
long now = Workflow.currentTimeMillis();

Pitfall 2: Non-Idempotent Compensating Activities

Symptom: A customer receives multiple credit card refunds for a single failed purchase.

Root Cause: A compensating activity failed due to a transient network timeout after issuing the refund, and Temporal retried the compensation without deduplication.

Fix: Pass unique transaction IDs into compensating activities and check prior execution state before re-executing refunds.

Pitfall 3: Indefinite Worker Thread Blocking

Symptom: Workflows hang forever without progressing or failing when a downstream service becomes unreachable.

Root Cause: Omitting StartToCloseTimeout on activity stubs.

Fix: Always specify explicit activity timeouts when building activity stubs:

ActivityOptions options = ActivityOptions.newBuilder()
        .setStartToCloseTimeout(Duration.ofSeconds(10))
        .setScheduleToCloseTimeout(Duration.ofMinutes(1))
        .build();

Frequently Asked Questions

Can I implement the Saga Pattern using Apache Kafka instead of Temporal?

Yes. Kafka is widely used for Saga Choreography. However, as the number of microservices increases, managing compensations, failure timeouts, and transaction states across Kafka topics becomes complex. Temporal provides centralized orchestration as code with built-in retries and state tracking.

What database does the Temporal Cluster use for event persistence?

The Temporal server supports production-grade persistence backends including PostgreSQL, MySQL, and Apache Cassandra. In development and testing, you can use Temporal’s lightweight embedded server or in-memory TestWorkflowEnvironment.

What happens if a compensating transaction fails?

Compensating transactions are retriable operations. Temporal will continually retry the failed compensation according to its configured RetryOptions. If an unrecoverable business failure occurs (e.g., an account has been closed), Temporal flags the workflow for human operator intervention through the Temporal Web UI.

Can a Temporal Saga run for days or months?

Yes. Because Temporal uses durable execution and event history replay, workflows can sleep for days, weeks, or months using Workflow.sleep(Duration.ofDays(30)) without consuming server memory or holding database connections while idle.

Is Temporal open-source and free for production enterprise use?

Yes. The core Temporal Server and the Java SDK are fully open source under the MIT License. Organizations can self-host the cluster on Kubernetes or utilize the managed Temporal Cloud service.

Authoritative Resources & Companion Code

Official Documentation & Reference Architecture:

• Temporal Java SDK Developer Guide — Official documentation for workflows, activities, sagas, and testing.
• Microservice Pattern: Saga (Chris Richardson) — Foundational architectural patterns for distributed data consistency.
• Spring Boot Reference Documentation — Official Spring Boot 4 guide and starter references.

Companion Workshop Repository:

• Full Companion Code on GitHub (workshop/architecture/saga-pattern-spring-boot-4-temporal) — Working Spring Boot 4 microservice, Temporal activities, Saga workflow, and 11-test automated suite.

Related Architectural Guides on Webcodein:

• What Is Spring Boot? A Complete Guide to Spring Boot 4 in 2026
• Clean Architecture: Implementing Hexagonal (Ports & Adapters) in Spring Boot 4
• Advanced Kafka: The Transactional Outbox Pattern with Spring Boot 4
• CQRS and Event Sourcing with Spring Boot 4 & Java 25
• High-Concurrency APIs with Java 25 Virtual Threads & Spring Boot 4

All code samples and architecture diagrams in this guide were verified using Java 25, Spring Boot 4.0.0, and Temporal SDK 1.24.1. Adapt timeouts and retry policies to your specific operational SLA requirements.