kataras/iris · error

build: view engine: %v

Error message

build: view engine: %v

What it means

Iris wraps any error returned by the view engine's Load() during app.Build() as 'build: view engine: %v'. Load() parses and pre-compiles all registered templates; a failure means templates or view configuration are broken, so Iris aborts startup instead of serving with a broken view layer.

Source

Thrown at iris.go:743

		}
	}

	if app.I18n.Loaded() {
		// {{ tr "lang" "key" arg1 arg2 }}
		app.view.AddFunc("tr", app.I18n.Tr)
		app.Router.PrependRouterWrapper(app.I18n.Wrapper())
	}

	if app.view.Registered() {
		app.logger.Debugf("Application: view engine %q is registered", app.view.Name())
		// view engine
		// here is where we declare the closed-relative framework functions.
		// Each engine has their defaults, i.e yield,render,render_r,partial, params...
		rv := router.NewRoutePathReverser(app.APIBuilder)
		app.view.AddFunc("urlpath", rv.Path)
		// app.view.AddFunc("url", rv.URL)
		if err := app.view.Load(); err != nil {
			return fmt.Errorf("build: view engine: %v", err)
		}
	}

	if !app.Router.Downgraded() {
		// router
		if _, err := injectLiveReload(app); err != nil {
			return fmt.Errorf("build: inject live reload: failed: %v", err)
		}

		if app.config.ForceLowercaseRouting {
			// This should always be executed first.
			app.Router.PrependRouterWrapper(func(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
				r.Host = strings.ToLower(r.Host)
				r.URL.Host = strings.ToLower(r.URL.Host)
				r.URL.Path = strings.ToLower(r.URL.Path)
				next(w, r)
			})
		}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Verify the template root directory path passed to the view engine is correct relative to the process working directory (use absolute paths or embed.FS).
2. Parse templates locally (e.g. html/template.ParseFiles) to find the exact template and line with the syntax error.
3. Check that all {{ template "name" }} references match existing defined template names and all functions used in templates are registered before Load().
4. If using embedded filesystems, ensure embed directives include the template files.
5. Read the wrapped inner error after 'build: view engine:' — it names the offending template file.

Example fix

// before
app.RegisterView(iris.HTML("./templates", ".html"))
// after (robust to CWD / embedded assets)
import _ "embed"
app.RegisterView(iris.HTMLFS(http.FS(templatesFS), ".").AddFunc("urlpath", nil))

root := "./templates"
if fi, err := os.Stat(root); err != nil || !fi.IsDir() {
    log.Fatalf("template dir %q missing: %v", root, err)
}
if err := template.Must(template.New("t").ParseGlob(filepath.Join(root, "*.html"))).Execute(io.Discard, nil); err != nil {
    log.Fatalf("template parse check failed: %v", err)
}

if err := app.Build(); err != nil {
    var viewErr error
    if strings.HasPrefix(err.Error(), "build: view engine:") {
        log.Fatalf("view/templates misconfigured: %v", err)
    }
    _ = viewErr
    log.Fatalf("build failed: %v", err)
}

When it happens

Trigger: Calling iris.New()/Run() with a registered view engine (e.g. app.RegisterView(iris.HTML(...))) whose template directory does not exist, contains syntax-invalid templates, references missing template names/includes, or uses an undefined template function.

Common situations: Wrong relative template dir path after changing working directory; template renamed or deleted but still referenced via {{ template ... }}; using a custom FuncMap name colliding with built-ins like 'urlpath'; CI/Docker images that exclude .html assets.

Related errors

• build: %w
• build: inject live reload: failed: %v
• build: router: %w
• failed to connect to the server after %d retries
• ErrEmptyFormField

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