apache/beam · error

expected 1 option, got

Error message

expected 1 option, got %v: %v

What it means

The cache hooks hook's Init validates the cache hook's options: exactly zero or one option is allowed, where the single option is the cache size. If more than one option is supplied, this error is returned, reporting the count and the raw option values.

Solutions

1. Pass exactly one option: the cache entry count, e.g. "1000".
2. Remove any extra comma/space-separated values from the hook option string.
3. Leave the option empty to use defaults (len(opts)==0 is accepted).

Example fix

// before
--cache_size="1000,unbounded"
// after
--cache_size="1000"

opts := strings.Split(cacheOpt, ",")
if len(opts) > 1 { return fmt.Errorf("cache hook takes at most 1 option, got %d", len(opts)) }
if len(opts) == 1 { if _, err := strconv.Atoi(opts[0]); err != nil { return err } }

if err := hook.Init(ctx); err != nil {
	log.Fatalf("cache hook option error: %v", err)
}

When it happens

Trigger: Configuring the harness cache hook (via --cache_size style hook options) with more than one comma/semicolon-separated option string so len(opts) > 1, e.g. "100,debug".

Common situations: Users appending extra arguments to the cache size option in worker harness flags, or copy-pasting hook option strings that include extraneous parameters.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• expected 1 option, got
• expected 2 options, got
• max time between dumps
• sample period should be greater than 1ms, got
• bad coder kind

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/harness/cache_hooks.go:37

	"context"
	"fmt"

	"github.com/apache/beam/sdks/v2/go/pkg/beam/core/util/hooks"
)

var (
	cacheSize int = 0
)

func init() {
	hf := func(opts []string) hooks.Hook {
		return hooks.Hook{
			Init: func(ctx context.Context) (context.Context, error) {
				if len(opts) == 0 {
					return ctx, nil
				}
				if len(opts) > 1 {
					return ctx, fmt.Errorf("expected 1 option, got %v: %v", len(opts), opts)
				}

				var count int
				_, err := fmt.Sscan(opts[0], &count)
				if err != nil {
					return nil, err
				}
				cacheSize = count
				return ctx, nil
			},
		}
	}
	hooks.RegisterHook("beam:go:hook:sideinputcache:capacity", hf)
}

View on GitHub (pinned to 12126d8942)