apache/beam · error

EnableHeapCaptureHook

Error message

EnableHeapCaptureHook: %s not registered

What it means

EnableHeapCaptureHook panics when the requested heap hook name is not present in heapCaptureHookRegistry, i.e. RegisterHeapCaptureHook was never called for it in this process. Enabling an unregistered hook would silently produce no profile data, so the library fails loudly instead.

Solutions

1. Blank-import the package that registers the heap hook before enabling it.
2. Ensure the name string exactly matches the registered identifier.
3. Update launch scripts/flags after hook renames; validate names against the registry.
4. Confirm the registering package is linked into the same binary that enables the hook.

Example fix

// before
perf.EnableHeapCaptureHook("heapprofile", "out") // panics: not registered
// after
import _ "github.com/apache/beam/sdks/go/pkg/beam/x/hooks/perf/heaphook" // registers "heapprofile"
perf.EnableHeapCaptureHook("heapprofile", "out")

import _ "path/to/hook/that/registers/heapprofile"
const heapHookName = "heapprofile" // must match the registered identifier
perf.EnableHeapCaptureHook(heapHookName, "out")

func enableHeap(name string, opts ...string) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("heap hook %q not registered: %v", name, r)
        }
    }()
    perf.EnableHeapCaptureHook(name, opts...)
}

When it happens

Trigger: Calling perf.EnableHeapCaptureHook(name, opts...) (commonly from getJobOptions reading pipeline/job options) with a name no registration provided — typo, missing import of the registering package, or stale option value after a rename.

Common situations: Enabling heap profiling via flags on workers built without the heap hook package; renaming the hook in code but not in launch scripts/CLI; copy-pasted option strings from a different pipeline.

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

• EnableProfCaptureHook
• EnableTraceCaptureHook
• A schema was provided without a data format (or viceversa)…
• AfterProcessingTime trigger set without a delay or…
• array len mismatch. decoding

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

Appendix: source

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

var heapCaptureHookRegistry = make(map[string]CaptureHookFactory)
var enabledHeapCaptureHooks []string

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

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

	enc := hooks.Encode(name, opts)

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

	enabledHeapCaptureHooks = append(enabledHeapCaptureHooks, enc)
	hooks.EnableHook("heap", enabledHeapCaptureHooks...)
}

View on GitHub (pinned to 12126d8942)