wavetermdev/waveterm · error

process died before emitting port

Error message

process died before emitting port

What it means

After starting the builder app, runBuilderApp waits up to 5 seconds for the subprocess to emit its port via a callback into portChan. If the process's WaitCh fires (process exited) before any port was received, this error is returned and the process is killed. It means the builder app crashed or exited early without announcing a port.

Source

Thrown at pkg/buildercontroller/buildercontroller.go:392

		StdinWriter: stdinPipe,
		WaitCh:      waitCh,
	}

	go func() {
		process.WaitRtn = cmd.Wait()
		close(waitCh)
	}()

	go bc.outputBuffer.ReadAll(stdoutPipe)
	go bc.outputBuffer.ReadAll(stderrPipe)

	errChan := make(chan error, 1)
	go func() {
		<-process.WaitCh
		select {
		case <-portChan:
		default:
			errChan <- fmt.Errorf("process died before emitting port")
		}
	}()

	timeout := time.NewTimer(5 * time.Second)
	defer timeout.Stop()

	select {
	case port := <-portChan:
		process.Port = port
		return process, nil
	case err := <-errChan:
		cmd.Process.Kill()
		return nil, err
	case <-timeout.C:
		cmd.Process.Kill()
		return nil, fmt.Errorf("timeout waiting for port")
	case <-ctx.Done():
		cmd.Process.Kill()

View on GitHub (pinned to a4447c1563)

Solutions

1. Check the builder output buffer/logs for the real crash message (panic, missing dependency)
2. Rebuild the builder binary ('make build') to eliminate a corrupted/stale artifact
3. Run the app being executed directly to reproduce its startup error
4. Verify required env vars and files the app needs are passed via builderEnv

process, err := bc.runBuilderApp(ctx, ...)
if err != nil && err.Error() == "process died before emitting port" {
    // surface builder output buffer contents to the user for the real cause
    return fmt.Errorf("builder exited early: %w (see output for crash details)", err)
}

When it happens

Trigger: Builder subprocess exits within 5s without writing a recognized port line to stdout/stderr — e.g. binary crash, bad args, missing runtime deps, immediate compile error in the app being run.

Common situations: Corrupted or stale builder binary; the underlying app panics at startup; incompatible protocol so the port regex never matches while the process exits for another reason.

Related errors

• timeout waiting for port
• failed to create stdout pipe: %w
• failed to create stderr pipe: %w
• failed to create stdin pipe: %w
• failed to start process: %w

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/f304b8fa6495599f. Report an issue: GitHub.