What causes "failed to register hook %s: %w" in pulumi/pulumi?

Read the inner wrapped error to find the concrete cause for hook .

failed to register hook %s: %w

Error message

failed to register hook %s: %w

What it means

During topological execution, each pcl.Hook node is registered via registerHookNode. Any failure inside that registration is wrapped with the hook's name so you know which hook failed.

Source

Thrown at pkg/pcl/runtime/interpreter.go:659

		switch node := node.(type) {
		case *pcl.ConfigVariable:
			// When executing a component program, config variables are supplied as component inputs
			// and set before the walk; don't override them with the enclosing program's config.
			if i.evalContext.HasVariable(node.Name()) {
				return nil
			}
			if diags := i.bindConfigVariable(ctx, node); diags.HasErrors() {
				return diags
			}
			return nil
		case *pcl.PulumiBlock:
			if err := i.enforceRequiredVersion(ctx); err != nil {
				return err
			}
			return nil
		case *pcl.Hook:
			if err := i.registerHookNode(ctx, node); err != nil {
				return fmt.Errorf("failed to register hook %s: %w", node.Name(), err)
			}
		case *pcl.LocalVariable:
			value, poison, diags := i.evalContext.Evaluate(node.Definition.Value)
			if poison != nil {
				i.evalContext.SetVariable(node.Name(), makePoisonValue(*poison))
				return nil
			}
			if diags.HasErrors() {
				return diags
			}
			if err := i.setVariable(ctx, node.Name(), value); err != nil {
				return fmt.Errorf("failed to set variable %s: %w", node.Name(), err)
			}
		case *pcl.Resource:
			if err := i.registerResource(ctx, node); err != nil {
				return fmt.Errorf("failed to register resource %s: %w", node.Name(), err)
			}
		case *pcl.ReadResource:

View on GitHub (pinned to 793f7b2e16)

Solutions

Read the inner wrapped error to find the concrete cause for hook <name>.
Verify the hook's target resource exists and is registered before the hook node in the program graph.
Check the hook's configuration (operation, handler) against the provider schema and correct the PCL source.

Example fix

// before
resource myRes ... hooks: { before: ["nonexistentHook"] }
// after
hook nonexistentHook defined and attached to an existing resource

Defensive patterns

Strategy: try-catch

Validate before calling

for _, h := range program.Nodes {
    if hook, ok := h.(*pcl.Hook); ok {
        if !hookTargetsExist(hook, resources) { return fmt.Errorf("hook %s target missing", hook.Name()) }
    }
}

Try / catch

if err := interp.Run(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to register hook ") {
        // extract hook name from the message and validate its config/targets
    }
}

Prevention

Define every hook before referencing it
Verify hook targets exist in the same program
Check hook configuration against the provider schema

When it happens

Trigger: Running a program containing a Hook node whose registration fails — e.g. hook targets an unknown resource, invalid hook configuration, or the underlying monitor RPC/schema lookup fails.

Common situations: Misconfigured before/after hooks in PCL source; hook referencing a resource that failed or does not exist; provider schema missing the hook definition.

Related errors

AI-assisted analysis of pulumi/pulumi@793f7b2e16 (2026-08-31). Data as JSON: /api/errors/83b561065b2116a1. Report an issue: GitHub.