apache/beam · error

EnableHook: hook not found

Error message

EnableHook: hook %s not found

What it means

hooks.EnableHook returns this error when the named hook is not present in the global hook registry. Hooks must first be registered (e.g. in a package init via RegisterHook) before they can be enabled with EnableHook(name, args...).

Solutions

1. Check the exact registered name against hooks.RegisterHook calls (search the repo for RegisterHook)
2. Add a blank import (import _ "path/to/hookpkg") so the package's init registers the hook before EnableHook runs
3. Enable hooks through the provided helpers (e.g. hooks.EnableProfCaptureHook) which use known-good names
4. Verify hook name spelling and that no version upgrade renamed it

Example fix

// before
hooks.EnableHook("beam.ProfCaptureHook")
// after
import _ "github.com/apache/beam/sdks/go/pkg/beam/core/runtime/hooks"
hooks.EnableHook(profcapture.HookName) // name matches RegisterHook exactly

// check the hook exists before enabling it by scanning registered hooks
// hooks exposes registration in init; enable via documented helper names, e.g.:
// hooks.EnableProfCaptureHook()
// or guard by name list maintained alongside RegisterHook calls
knownHooks := map[string]bool{"your.hook.name": true} // keep in sync with RegisterHook
if !knownHooks[name] {
    return fmt.Errorf("hook %q not registered; call RegisterHook first", name)
}

if err := hooks.EnableHook(name); err != nil {
    if strings.Contains(err.Error(), "not found") {
        // fall back: register then enable, or skip enabling
    }
    return err
}

When it happens

Trigger: Calling hooks.EnableHook("name", ...) with a name that was never passed to hooks.RegisterHook, or after the hook was registered in a package that was never imported (so its init never ran).

Common situations: Typo in the hook name; enabling a built-in hook (e.g. capture hooks) without importing the package that registers it; registering hooks inside a test file that is not linked into the binary; removing/renaming a hook in a newer version of Beam.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• bad coder kind
• bad CoGBK
• bad combinefn
• bad decode
• bad decoding function

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/util/hooks/hooks.go:229

	}

	for _, h := range r.enabledHookOrder {
		opts := r.enabledHooks[h]
		r.activeHooks[h] = r.hookRegistry[h](opts)
	}
}

// DeserializeHooksFromOptions extracts the hook configuration information from the options and configures
// the hooks with the supplied options.
func DeserializeHooksFromOptions(ctx context.Context) {
	defaultRegistry.DeserializeHooksFromOptions(ctx)
}

func (r *registry) EnableHook(name string, args ...string) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	if _, ok := r.hookRegistry[name]; !ok {
		return errors.Errorf("EnableHook: hook %s not found", name)
	}
	r.disableHook(name)
	r.enabledHookOrder = append(r.enabledHookOrder, name)
	r.enabledHooks[name] = args
	return nil
}

// EnableHook enables the hook to be run for the pipeline. It will be
// receive the supplied args when the pipeline executes.
// Repeat calls for the same hook will overwrite previous args,
// and move the hook to the end of the ordering.
// Multiple options can be provided,
// as this is necessary if a hook wants to compose behavior.
func EnableHook(name string, args ...string) error {
	return defaultRegistry.EnableHook(name, args...)
}

func (r *registry) IsEnabled(name string) (bool, []string) {

View on GitHub (pinned to 12126d8942)