What causes "must supply dot_file argument" in apache/beam?

Pass --dot_file=graph.dot (a writable path) on the command line.

must supply dot_file argument

Error message

must supply dot_file argument

What it means

The dot runner's Execute produces a DOT graph of the pipeline and writes it to the file given by the required --dot_file flag. If the flag was not supplied (empty string), it returns this error before building the pipeline. The runner has no meaningful default output path.

Source

Thrown at sdks/go/pkg/beam/runners/dot/dot.go:42

	"os"

	"github.com/apache/beam/sdks/v2/go/pkg/beam"
	dotlib "github.com/apache/beam/sdks/v2/go/pkg/beam/core/util/dot"
	"github.com/apache/beam/sdks/v2/go/pkg/beam/internal/errors"
)

func init() {
	beam.RegisterRunner("dot", Execute)
}

// Code for making DOT graphs of the Graph data structure

var dotFile = flag.String("dot_file", "", "DOT output file to create")

// Execute produces a DOT representation of the pipeline.
func Execute(ctx context.Context, p *beam.Pipeline) (beam.PipelineResult, error) {
	if *dotFile == "" {
		return nil, errors.New("must supply dot_file argument")
	}

	edges, nodes, err := p.Build()
	if err != nil {
		return nil, errors.New("can't get data to render")
	}

	var buf bytes.Buffer
	if err := dotlib.Render(edges, nodes, &buf); err != nil {
		return nil, err
	}
	return nil, os.WriteFile(*dotFile, buf.Bytes(), 0644)
}

View on GitHub (pinned to 12126d8942)

Solutions

Pass --dot_file=graph.dot (a writable path) on the command line.
If invoking programmatically, ensure flag.Parse() runs or set *dotFile (or use flag.Set("dot_file", "graph.dot")) before Execute.
Check that the value is non-empty and the directory is writable.

Example fix

// before
// go run ./pipeline --runner=dot
// after
// go run ./pipeline --runner=dot --dot_file=out/graph.dot

Defensive patterns

Strategy: validation

Validate before calling

if *dotFile == "" {
    return errors.New("--dot_file is required for the dot runner; pass --dot_file=graph.dot")
}

Try / catch

if _, err := beam.Execute(ctx, p); err != nil && strings.Contains(err.Error(), "dot_file") {
    // re-run with the flag or set flag.Set("dot_file", "graph.dot") before Execute
}

Prevention

Always pass --dot_file when using the dot runner.
Call flag.Parse() before Execute when invoking programmatically.
Wrap the dot runner in a launcher that supplies a default output path.
Verify the target directory exists and is writable to avoid the follow-on write failure.

When it happens

Trigger: Running a pipeline with the dot runner without passing --dot_file=<path>, or invoking beam.Execute with the dot runner registered but the dotFile flag never set (e.g. calling Execute programmatically without flag.Parse).

Common situations: Forgetting the --dot_file flag on the command line; setting up the dot runner in tests without initializing flags (no flag.Parse() call); empty value passed as --dot_file="".

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

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