apache/beam · error

endpoint not defined

Error message

endpoint not defined

What it means

beamctl's dial() refuses to connect when the --endpoint flag/value is empty, returning errors.New("endpoint not defined") before any gRPC dial is attempted. All subcommands (stage, list, info) route through dial, so none can run without an endpoint.

Source

Thrown at sdks/go/cmd/beamctl/cmd/root.go:50

		Use:   "beamctl",
		Short: "Apache Beam command line client",
	}

	id       string
	endpoint string
)

func init() {
	RootCmd.AddCommand(artifactCmd, provisionCmd)
	RootCmd.PersistentFlags().StringVarP(&endpoint, "endpoint", "e", "", "Server endpoint, such as localhost:123")
	RootCmd.PersistentFlags().StringVarP(&id, "id", "i", "", "Client ID")
}

// dial connects via gRPC to the given endpoint and returns the connection
// and the context to use.
func dial() (context.Context, *grpc.ClientConn, error) {
	if endpoint == "" {
		return nil, nil, errors.New("endpoint not defined")
	}

	ctx := grpcx.WriteWorkerID(context.Background(), id)
	cc, err := grpcx.Dial(ctx, endpoint, time.Minute)
	return ctx, cc, err
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass the runner endpoint explicitly: beamctl list --endpoint=<host:port>.
2. Check the flag spelling (--endpoint) so pflag actually binds the value.
3. Verify the Beam runner/job-service address is reachable and correctly formatted (host:port).

Example fix

// before
beamctl list
// after
beamctl list --endpoint=localhost:8073

if endpoint == "" {
	return fmt.Errorf("--endpoint is required, e.g. --endpoint=localhost:8073")
}

if err := cmd.RunE(cmdCtx, args); err != nil && strings.Contains(err.Error(), "endpoint not defined") {
	return fmt.Errorf("usage: beamctl %s --endpoint=<host:port>", cmdName)
}

When it happens

Trigger: Running `beamctl stage/list/info` without the --endpoint flag, or with the endpoint variable left unset (empty string).

Common situations: Forgetting the flag in scripts/CI, or expecting a default localhost endpoint that beamctl does not provide; also occurs when the flag is defined with an empty default and the env var is missing.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• --pid_file must be specified with --start
• --stdout_file must be specified with --background
• provided transform_name_mapping without setting the --update
• must supply dot_file argument
• failed to read metadata from context

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