apache/beam · error

EnableProfCaptureHook

Error message

EnableProfCaptureHook: %s not registered

What it means

EnableProfCaptureHook looks up the requested hook name in profCaptureHookRegistry and panics if it was never registered via RegisterProfCaptureHook. Enabling is separate from registering so that pipelines can reference hooks only when the corresponding instrumentation package was imported.

Solutions

  1. Ensure the package that calls RegisterProfCaptureHook for that exact name is imported (even blank import _ "path/to/hook") before enabling.
  2. Verify the name string passed to EnableProfCaptureHook matches the registered identifier exactly.
  3. If the name comes from a flag/job option, validate it against registered hook names before enabling.
  4. Check that the same binary builds the pipeline and runs the worker — the registration must exist in the process that enables it.

Example fix

// before
import (
    "github.com/apache/beam/sdks/go/pkg/beam"
    "github.com/apache/beam/sdks/go/pkg/beam/x/hooks/perf"
)
perf.EnableProfCaptureHook("cpuprofile", "out.prof") // panics: never registered
// after
import (
    _ "github.com/apache/beam/sdks/go/pkg/beam/x/hooks/perf/cpuhook" // registers "cpuprofile"
    "github.com/apache/beam/sdks/go/pkg/beam/x/hooks/perf"
)
perf.EnableProfCaptureHook("cpuprofile", "out.prof")
Defensive patterns

Strategy: validation

Validate before calling

// ensure the registering package is linked
import _ "path/to/hook/that/registers/cpuprofile"
// and confirm the exact name before enabling
const want = "cpuprofile"
perf.EnableProfCaptureHook(want, "out.prof")

Try / catch

func enableProf(name string, opts ...string) (enabled bool) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("prof hook %q not registered: %v", name, r)
        }
    }()
    perf.EnableProfCaptureHook(name, opts...)
    return true
}

Prevention

When it happens

Trigger: Calling perf.EnableProfCaptureHook(name, opts...) (often via getJobOptions building pipeline options) with a name that has no matching RegisterProfCaptureHook call in the binary — e.g. a typo in the name or the profiling package not imported at all.

Common situations: Passing a profile hook name through job options/flags on a worker binary that doesn't import the package that registers the hook; renaming a hook in one place but not the option value; enabling a hook in a pipeline builder that never linked the hook's package.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/x/hooks/perf/perf.go:150

	}
	hooks.RegisterHook("heap", hf)
}

// RegisterProfCaptureHook registers a CaptureHookFactory for the
// supplied identifier. It panics if the same identifier is
// registered twice.
func RegisterProfCaptureHook(name string, c CaptureHookFactory) {
	if _, exists := profCaptureHookRegistry[name]; exists {
		panic(fmt.Sprintf("RegisterProfCaptureHook: %s registered twice", name))
	}
	profCaptureHookRegistry[name] = c
}

// EnableProfCaptureHook actives a registered profile capture hook for a given pipeline.
func EnableProfCaptureHook(name string, opts ...string) {
	_, exists := profCaptureHookRegistry[name]
	if !exists {
		panic(fmt.Sprintf("EnableProfCaptureHook: %s not registered", name))
	}

	enc := hooks.Encode(name, opts)

	for i, h := range enabledProfCaptureHooks {
		n, _ := hooks.Decode(h)
		if h == n {
			// Rewrite the registration with the current arguments
			enabledProfCaptureHooks[i] = enc
			hooks.EnableHook("prof", enabledProfCaptureHooks...)
			return
		}
	}

	enabledProfCaptureHooks = append(enabledProfCaptureHooks, enc)
	hooks.EnableHook("prof", enabledProfCaptureHooks...)
}

View on GitHub (pinned to 12126d8942)