What causes "error creating local job server: %v" in apache/beam?

Read the wrapped %v cause; if it is an address-in-use error, free the port or let the server pick an ephemeral port.

error creating local job server: %v

Error message

error creating local job server: %v

What it means

This error wraps a failure from prism.CreateJobServer when makeJobClient in the prism CLI tries to start an in-process local Beam job server for the Go SDK harness. The local job server (which serves the JobService gRPC API to the pipeline runner) failed to create or start, so the CLI cannot hand back a JobServiceClient. The wrapped %v carries the underlying cause, typically a network bind failure.

Source

Thrown at sdks/go/cmd/prism/prism.go:83

		if err := prism.CreateWebServer(ctx, cli, prism.Options{Port: *webPort}); err != nil {
			log.Fatalf("error creating web server: %v", err)
		}
	}
	// Block main thread forever to keep main from exiting.
	<-ctx.Done()
}

func makeJobClient(ctx context.Context, opts prism.Options, endpoint string) (jobpb.JobServiceClient, error) {
	if endpoint != "" {
		clientConn, err := grpc.DialContext(ctx, endpoint, grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithBlock())
		if err != nil {
			return nil, fmt.Errorf("error connecting to job server at %v: %v", endpoint, err)
		}
		return jobpb.NewJobServiceClient(clientConn), nil
	}
	cli, err := prism.CreateJobServer(ctx, opts)
	if err != nil {
		return nil, fmt.Errorf("error creating local job server: %v", err)
	}
	return cli, nil
}

View on GitHub (pinned to 12126d8942)

Solutions

Read the wrapped %v cause; if it is an address-in-use error, free the port or let the server pick an ephemeral port.
Check that loopback networking works in your environment (container/sandbox restrictions often block local listeners).
Re-run with fewer custom opts or upgrade the Beam Go SDK to get fixes in CreateJobServer.
Verify no security software (firewall, SELinux, AppArmor) is preventing binding to 127.0.0.1.

Example fix

// before
cli, err := prism.CreateJobServer(ctx, opts)
if err != nil {
	return nil, fmt.Errorf("error creating local job server: %v", err)
}
// after
cli, err := prism.CreateJobServer(ctx, opts)
if err != nil {
	return nil, fmt.Errorf("error creating local job server (endpoint=%v): %w", endpoint, err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

if ln, err := net.Listen("tcp", "127.0.0.1:0"); err != nil { return fmt.Errorf("cannot bind local listener: %w", err) } else { ln.Close() }

Try / catch

cli, err := prism.CreateJobServer(ctx, opts)
if err != nil {
	var nerr net.Error
	if errors.As(err, &nerr) { log.Printf("network problem starting job server: %v", nerr) }
	return nil, err
}

Prevention

Test loopback binding in CI containers before running Beam Go pipelines.
Avoid hardcoding ports; use ephemeral ports for the local job server.
Check container/network sandbox policies that forbid local listeners.

When it happens

Trigger: Calling prism's main pipeline entry which invokes makeJobClient with an empty/local endpoint, and CreateJobServer fails to listen on the loopback port or fails to start the gRPC server.

Common situations: Port exhaustion or a port already in use on the machine; firewall/SELinux blocking loopback binds; restricted container environments without loopback networking; a corrupted or unsupported environment option passed via opts.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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