gohugoio/hugo · error

failed to read %q: %w

Error message

failed to read %q: %w

What it means

Returned from the Hugo import resolver's OnLoad callback when os.ReadFile(args.Path) fails for a file resolved into the ns-hugo-imp namespace. The wrapped error contains the OS-level read failure.

Source

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

			return api.OnResolveResult{Path: m.Filename, Namespace: NsHugoImport}, nil
		}

		// Fall back to ESBuild's resolve.
		return api.OnResolveResult{}, nil
	}

	importResolver := api.Plugin{
		Name: "hugo-import-resolver",
		Setup: func(build api.PluginBuild) {
			build.OnResolve(api.OnResolveOptions{Filter: `.*`},
				func(args api.OnResolveArgs) (api.OnResolveResult, error) {
					return resolveImport(args)
				})
			build.OnLoad(api.OnLoadOptions{Filter: `.*`, Namespace: NsHugoImport},
				func(args api.OnLoadArgs) (api.OnLoadResult, error) {
					b, err := os.ReadFile(args.Path)
					if err != nil {
						return api.OnLoadResult{}, fmt.Errorf("failed to read %q: %w", args.Path, err)
					}
					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
					}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Verify the file at the printed path exists and is readable.
2. Restart hugo server to re-resolve against the current filesystem.
3. Check submodule and git LFS state to ensure real content is present.

Treat read failures during server mode as transient: on this error, re-resolve the asset once and retry; on persistent failure surface the path to the user as a missing-asset diagnostic.

When it happens

Trigger: An asset was resolved successfully but, by the time esbuild loads it via the OnLoad callback, the file is unreadable — deleted, moved, or has restrictive permissions between resolve and load.

Common situations: Hugo server with a file rename/delete happening concurrently; CI pulling assets via a submodule that wasn't initialized; OS permission denied; git LFS pointer file instead of real content.

Related errors

• failed to read import %q: %w
• inject: absolute paths not supported, must be relative to /a
• inject: file %q not found
• ImportOnLoadFunc failed to resolve %q
• Error reading from stdin

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