kataras/iris · error

%s: %w

Error message

%s: %w

What it means

During HTMLEngine.Load, each discovered template file is read from the embedded/OS filesystem via the asset function. If reading fails (file missing, unreadable, fs error), the engine wraps the underlying error with the template path using fmt.Errorf("%s: %w", path, err) so the offending template file is identified.

Source

Thrown at view/html.go:284

		if info == nil || info.IsDir() {
			return nil
		}

		if s.extension != "" {
			if !strings.HasSuffix(path, s.extension) {
				return nil
			}
		}

		if s.rootDir == rootDirName {
			path = strings.TrimPrefix(path, rootDirName)
			path = strings.TrimPrefix(path, "/")
		}

		buf, err := asset(s.fs, path)
		if err != nil {
			return fmt.Errorf("%s: %w", path, err)
		}

		return s.parseTemplate(path, buf, nil)
	})

	if s.onLoaded != nil {
		s.onLoaded()
	}

	if err != nil {
		return err
	}

	if s.Templates == nil {
		return fmt.Errorf("no templates found")
	}

	return nil

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Inspect the wrapped inner error (%w) for the real fs failure and fix the path or missing file.
2. Verify the embedded FS includes the template directory: //go:embed templates and templates/* passed to the engine.
3. Ensure the root directory name used by the loader matches the top-level folder in the fs so path trimming yields valid keys.
4. Call Load() at startup and log the full error chain to catch it before serving requests.

Example fix

// before
//go:embed templates/*.html
var tmplFS embed.FS
engine := html.New(tmplFS, ".html")
// after (ensure extension/root match what Loader registered)
//go:embed templates
var tmplFS embed.FS
engine := html.New(tmplFS, ".html").Reload(true)

entries, err := fs.ReadDir(tmplFS, "templates")
if err != nil || len(entries) == 0 {
    log.Fatalf("embedded templates missing or empty: %v", err)
}

if err := engine.Load(); err != nil {
    log.Fatalf("html engine load failed: %v", err) // error includes template path: root cause
}

When it happens

Trigger: HTMLEngine.Load (also invoked lazily by ExecuteWriter) iterating registered asset paths where s.fs.ReadFile/asset fails — e.g. an embedded FS that does not contain the template directory, or a path that was trimmed incorrectly (rootDirName prefix mismatch).

Common situations: Embedding templates with go:embed but forgetting the directive or embedding the wrong directory; building to a directory without the templates; using a relative loader root that doesn't match the embedded folder name so trimmed paths no longer resolve.

Related errors

• %s: %w
• no templates found
• err
• err
• err

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/b0efd97eab2251c1. Report an issue: GitHub.