apache/beam · error

EnableTraceCaptureHook

Error message

EnableTraceCaptureHook: %s not registered

What it means

EnableTraceCaptureHook checks traceCaptureHookRegistry for the given name and panics when it was never registered via RegisterTraceCaptureHook. This separates enabling (per pipeline/job) from registration (per binary/import), so enabling an unknown hook is a programmer/configuration error.

Solutions

1. Blank-import the package that registers the trace hook (e.g. _ ".../hooks/perf/tracehook") before enabling.
2. Match the enabled name exactly against the registered identifier.
3. Validate hook names coming from flags/job options against the registry.
4. Ensure the enabling binary and the worker binary both link the hook registration package.

Example fix

// before
perf.EnableTraceCaptureHook("tracing", "opts") // panics: not registered
// after
import _ "github.com/apache/beam/sdks/go/pkg/beam/x/hooks/perf/tracehook" // registers "tracing"
perf.EnableTraceCaptureHook("tracing", "opts")

import _ "path/to/hook/that/registers/tracing"
const traceHookName = "tracing" // shared constant with the registration site
perf.EnableTraceCaptureHook(traceHookName)

func enableTrace(name string, opts ...string) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("trace hook %q unavailable: %v", name, r)
        }
    }()
    perf.EnableTraceCaptureHook(name, opts...)
}

When it happens

Trigger: Calling perf.EnableTraceCaptureHook(name, opts...) with a name absent from the trace hook registry — misspelled name, hook package not imported into the worker binary, or the option string carrying a stale hook identifier.

Common situations: Job options/flags referencing a trace hook that only exists in another binary; refactor renamed the hook but old option values persist; worker containers built without the instrumentation 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

• EnableHeapCaptureHook
• EnableProfCaptureHook
• 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/3a09cd3a5ca708df. Report an issue: GitHub.

Appendix: source

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

}

var traceCaptureHookRegistry = make(map[string]CaptureHookFactory)
var enabledTraceCaptureHooks []string

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

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

	enc := hooks.Encode(name, opts)
	for i, h := range enabledTraceCaptureHooks {
		n, _ := hooks.Decode(h)
		if h == n {
			// Rewrite the registration with the current arguments
			enabledTraceCaptureHooks[i] = enc
			hooks.EnableHook("trace", enabledTraceCaptureHooks...)
			return
		}
	}
	enabledTraceCaptureHooks = append(enabledTraceCaptureHooks, enc)
	hooks.EnableHook("trace", enabledTraceCaptureHooks...)
}

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

View on GitHub (pinned to 12126d8942)