Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Proposal: handle SIGTERM by default to initiate graceful worker shutdown

Open
  • Is something wrong?
#3,135 1 comment 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@eamsden is already working on this.

Since Oct 8, 2026.

Assessment

This issue has not been assessed yet.

Description

Summary

A Temporal Java worker installs no graceful-shutdown signal handling by default. The JVM runs shutdown hooks on SIGTERM, but the SDK registers none that drain the worker, so a bare worker exits without stopping polling or draining in-flight work. In-flight activities are abandoned and retried server-side after their timeouts.

Proposal: consider a built-in option to initiate WorkerFactory shutdown on SIGTERM by default (opt-out-able), so the common containerized case — stop polling → drain → cancel — works without extra wiring.

Current workaround

A JVM shutdown hook calling WorkerFactory.shutdown() → awaitTermination(timeout) → shutdownNow() (plus WorkerOptions.setAllowActivityHeartbeatDuringShutdown(true) to let a heartbeating activity finish during the drain); or run under the Spring Boot starter, which wires it.

Precedent

The TypeScript SDK already does this: its Runtime installs handlers for SIGINT/SIGTERM/SIGQUIT/SIGUSR2 by default and calls shutdown() on every worker.

Trade-offs / open questions (why it is not already the default)

  • A worker usually runs inside a larger process (HTTP server, DI host, other lifecycle). A library installing a process-global signal handler can conflict with the host application's own signal handling, so any default must be clearly opt-out-able and should no-op when a host framework already owns the signal.
  • Default-on vs. an explicit opt-in flag?
  • If added, match the TypeScript semantics and honor the existing grace/drain config.

Why this comes up

SIGTERM-before-SIGKILL is the standard stop protocol for Kubernetes, Cloud Run, ECS, docker stop, and systemd. Users commonly expect a worker to drain on SIGTERM without extra wiring, and it is a recurring support question (e.g. https://community.temporal.io/t/proper-way-to-shutdown-on-sigterm-sigint/5485).

Related: #2026.

One of a set of sibling issues on default SIGTERM handling across the SDKs that do not auto-handle it today (Go, Python, Java, .NET, Ruby, Rust). TypeScript already does; PHP delegates process lifecycle to RoadRunner.

Dominant language
Java
Stars
434
Forks
260
Avg merge
2d 11h
Merged PRs (30d)
19

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from temporalio/sdk-java

All issues in temporalio/sdk-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.