bug: useRealtimeRun onComplete fires prematurely in self-hosted environment (Traefik + Docker Compose)

[bbreunig]

Provide environment information

Environment Information

System:

OS: macOS 15.7
CPU: (36) x64 Intel(R) Xeon(R) W-2191B CPU @ 2.30GHz
Memory: 71.57 GB / 128.00 GB
Shell: 5.9 - /bin/zsh

Binaries:

Node: 23.6.1 - /Users/<home>/.nvm/versions/node/v23.6.1/bin/node
npm: 10.9.2 - /Users/<home>/.nvm/versions/node/v23.6.1/bin/npm
pnpm: 10.19.0 - /Users/<home>/Library/pnpm/pnpm

Reproduction Environment

• Hosting: Self-hosted using the standard Trigger.dev docker-compose.yml.
• Reverse Proxy: Traefik.
• Hook Config: Using baseURL pointing to the Traefik entrypoint for the Trigger API.
• SDK Versions: @trigger.dev/sdk@4.3.2, @trigger.dev/react-hooks@4.3.2.
• Framework: Next.js 16.10.0 / React 19.2.0

Infrastructure Details

The instance is running behind Traefik using the default Docker Compose setup. While the onComplete callback fires early, the run state returned by the hook does continue to update correctly in the UI as the task progresses, eventually reaching COMPLETED. This suggests the realtime connection itself is working, but the logic governing the callback trigger is misfiring in this network environment.

Describe the bug

When using the useRealtimeRun hook with a self-hosted Trigger.dev instance, the onComplete callback fires immediately upon the first successful data fetch, even if the run is still in an active state (e.g., EXECUTING).

Reproduction repo

None

To reproduce

Reproduction Steps

1. Trigger a task that includes a significant delay (e.g., 5-10 seconds).
2. Use useRealtimeRun in a client component with a baseURL and an onComplete callback.

const { run } = useRealtimeRun(runId, {
     accessToken: publicToken,
     baseURL: "https://your-self-hosted-trigger.com",
     onComplete: (run) => {
       console.log("onComplete called with status:", run.status);
     }
   });

3. Observe that onComplete is called almost immediately after the component mounts.
4. Logging the run object inside onComplete shows status: "EXECUTING".### Expected Behavior
   onComplete should only be called once the run reaches a terminal state (COMPLETED, FAILED, CANCELED, CRASHED).

Actual Behavior

onComplete is called immediately with the non-terminal state.

Additional information

I also checked traefik logs but there were no issues.

[nicktrn]

@claude please investigate what might cause this to only affect self-hosters and propose a fix

[claude]

Claude finished @nicktrn's task in 2m 55s —— View job • claude/issue-2856-20260109-1025 • Create PR ➔

---

Summary

I identified and fixed the root cause of the onComplete callback firing prematurely in self-hosted environments.

Root Cause

The issue was in packages/react-hooks/src/hooks/useRealtime.ts. The onComplete callback was being triggered based on two conditions:

1. isComplete - set to true when the SSE stream ends
2. run - the run object exists

The problem is that isComplete becomes true whenever the stream connection ends, which can happen prematurely due to:

• Reverse proxy timeouts (Traefik, nginx, etc. often have 60-second defaults)
• Network interruptions
• Connection resets

In self-hosted environments with Traefik, the Electric SQL streaming connection was being closed by the reverse proxy before the run actually completed, triggering onComplete with a run still in EXECUTING status.

The Fix

Changed the condition from checking run (run object exists) to checking run?.finishedAt (run has actually finished):

-    if (isComplete && run && options?.onComplete && !hasCalledOnCompleteRef.current) {
+    if (isComplete && run?.finishedAt && options?.onComplete && !hasCalledOnCompleteRef.current) {

This ensures onComplete only fires when the run has actually reached a terminal state (COMPLETED, FAILED, CANCELED, CRASHED, etc.), not just when the stream connection ends.

Files Changed

• packages/react-hooks/src/hooks/useRealtime.ts - Fixed both useRealtimeRun and useRealtimeRunWithStreams hooks

---

|

[nicktrn]

@bbreunig I think the root cause here makes sense. SSE stream ends prematurely -> marked as completed. As it's almost immediate it won't be due to 60s timeout or similar though. We can try to "fix" from our end but that won't solve the real issue for you. Could still be traefik related. Also worth checking electric and webapp logs

[bbreunig]

Upon further investigation I noticed the following:

1. There are no logs in electric, webapp, worker or proxy (traefik) that suggest any issue with the stream.
2. I did not see any SSE connection in my Dev Tools.

There is a note in electric SQL that mentions for SSE to work the ShapeStream needs liveSSL: true See Electric SQL Docs
This is not the case with your implementation:

trigger.dev/packages/core/src/v3/apiClient/stream.ts

Lines 42 to 54 in 839d5e8

	const shapeStream = new ShapeStream({
	url,
	headers: {
	...options?.headers,
	"x-trigger-electric-version": "1.0.0-beta.1",
	[API_VERSION_HEADER_NAME]: API_VERSION,
	},
	fetchClient: options?.fetchClient,
	signal: abortController.signal,
	onError: (e) => {
	options?.onError?.(e);
	},
	});

Claudes solution proposition should work as far as I have checked.