gohugoio/hugo · error

ImportOnLoadFunc failed to resolve %q

Error message

ImportOnLoadFunc failed to resolve %q

What it means

Returned when the ImportOnLoadFunc callback (used by js.Batcher to provide content for imports resolved via ImportOnResolveFunc into the ns-hugo-imp-func namespace) returns an empty string. The resolver previously claimed the path but the loader can't produce content.

Source

Thrown at internal/js/esbuild/resolve.go:335

					c := string(b)

					return api.OnLoadResult{
						// See https://github.com/evanw/esbuild/issues/502
						// This allows all modules to resolve dependencies
						// in the main project's node_modules.
						ResolveDir: opts.ResolveDir,
						Contents:   &c,
						Loader:     opts.loaderFromFilename(args.Path),
					}, nil
				})
			build.OnLoad(api.OnLoadOptions{Filter: `.*`, Namespace: NsHugoImportResolveFunc},
				func(args api.OnLoadArgs) (api.OnLoadResult, error) {
					c, err := opts.ImportOnLoadFunc(args)
					if err != nil {
						return api.OnLoadResult{}, err
					}
					if c == "" {
						return api.OnLoadResult{}, fmt.Errorf("ImportOnLoadFunc failed to resolve %q", args.Path)
					}

					return api.OnLoadResult{
						ResolveDir: opts.ResolveDir,
						Contents:   &c,
						Loader:     opts.loaderFromFilename(args.Path),
					}, nil
				})
		},
	}

	params := opts.Params
	if params == nil {
		// This way @params will always resolve to something.
		params = make(map[string]any)
	}

	b, err := json.Marshal(params)

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Inspect the import path printed — verify it matches a registered script key.
2. Ensure every script option set on the batcher has a valid Resource.
3. Restart hugo server to clear stale import cache and re-register scripts.

// Before triggering a batch build, ensure every script option that will be
// resolved via ImportOnResolveFunc also has a Resource that ImportOnLoadFunc
// can read. Verify the import path key matches the registered script key.
for _, key := range registeredScriptKeys {
    if _, ok := state.importResource.Get(key); !ok {
        return fmt.Errorf("script %q registered but no resource attached", key)
    }
}

When it happens

Trigger: In a batch build, an import was routed via ImportOnResolveFunc to the NsHugoImportResolveFunc namespace, but at load time the corresponding ImportOnLoadFunc returns ("", nil) — no error, just no content. Typically state.importResource.Get(imp) returned not-found for a path that was supposed to be registered.

Common situations: Race between script option registration and import resolution; template provides an Import path that doesn't map back to a registered resource; custom batch option maps with mismatched keys; rename of a script mid-session leaving stale resolver state.

Related errors

• failed to build JS batch: %w
• id must be set
• id must not contain backslashes
• id must not contain forward slashes
• failed to build JS batch %q: %w

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/0590e4f24ddc0e02. Report an issue: GitHub.