apache/beam · critical

empty port

Error message

empty port

What it means

DataChannelManager.Open establishes a read/write gRPC data channel to the Beam runner's data service, which is addressed via port.URL. An empty URL means the harness was given no usable logging/data API endpoint, so the manager panics instead of dialing a meaningless address.

Source

Thrown at sdks/go/pkg/beam/core/runtime/harness/datamgr.go:115

	s.mu.Lock()
	defer s.mu.Unlock()
	s.closed = true
	err := s.mgr.closeInstruction(s.instID, s.openPorts)
	s.mgr = nil
	return err
}

// DataChannelManager manages data channels over the Data API. A fixed number of channels
// are generally used, each managing multiple logical byte streams. Thread-safe.
type DataChannelManager struct {
	ports map[string]*DataChannel
	mu    sync.Mutex // guards the ports map
}

// Open opens a R/W DataChannel over the given port.
func (m *DataChannelManager) Open(ctx context.Context, port exec.Port) (*DataChannel, error) {
	if port.URL == "" {
		panic("empty port")
	}

	m.mu.Lock()
	defer m.mu.Unlock()

	if m.ports == nil {
		m.ports = make(map[string]*DataChannel)
	}
	if con, ok := m.ports[port.URL]; ok {
		return con, nil
	}

	ch, err := newDataChannel(ctx, port)
	if err != nil {
		return nil, err
	}
	ch.forceRecreate = func(id string, err error) {
		switch status.Code(err) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the runner passes the data endpoint: check that the worker is launched with the correct --workerHarnessContainerImage and endpoint pipeline options.
2. When testing/using the harness directly, populate exec.Port{URL: "host:port"} (e.g. from the environment variable the runner sets) before calling Open.
3. If launching containers manually, set the RUNNER/BEAM harness endpoint env or flags exactly as the runner expects.

Example fix

// before
ch, err := mgr.Open(ctx, exec.Port{})
// after
if port.URL == "" {
    return nil, fmt.Errorf("data endpoint URL not configured")
}
ch, err := mgr.Open(ctx, port)

if port.URL == "" {
    return fmt.Errorf("data channel port URL is empty; check runner endpoint configuration")
}

defer func() {
    if r := recover(); r != nil {
        log.Fatalf("failed to open data channel: %v", r)
    }
}()

When it happens

Trigger: Calling DataChannelManager.Open with an exec.Port whose URL field is "" — typically when the harness bootstrap passed an empty --loggingEndpoint/--dataEndpoint or the pipeline options omitted the data API service address.

Common situations: Running a Go Beam worker outside the runner-managed environment (custom container, Flink/Spark/Spark runner misconfiguration) where the endpoint environment variables are missing; typo'd pipeline option that blanks the port URL; unit-testing the harness with a zero-value exec.Port.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• unknown ShutdownMode: %v
• internal: log message buffer closed
• side input closed
• failed to read metadata from context
• trigger.AfterCount(%v) must be a positive integer

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/5014a1340a7e899b. Report an issue: GitHub.