kataras/iris · error

build: inject live reload: failed: %v

Error message

build: inject live reload: failed: %v

What it means

During Application.Build(), Iris injects the live-reload middleware (used when Configurator enables it, e.g. injected via injectLiveReload) and wraps any failure as 'build: inject live reload: failed: %v'. The live reload component watches/patches assets and needs an available reload address; if it cannot be initialized the build aborts.

Source

Thrown at iris.go:750

	}

	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)
			})
		}

		// create the request handler, the default routing handler
		routerHandler := router.NewDefaultHandler(app.config, app.logger)
		err := app.Router.BuildRouter(app.ContextPool, routerHandler, app.APIBuilder, false)
		if err != nil {
			return fmt.Errorf("build: router: %w", err)
		}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Read the wrapped inner error after 'failed:' to identify the underlying cause (usually bind/port or config).
2. Disable live reload for this environment (do not enable the reload configurator in production/CI).
3. Free the port used by live reload or change its configured address.
4. If behind a proxy, forward or exclude the live-reload endpoint.
5. Upgrade Iris if the inner error points to an injectLiveReload bug.

Example fix

// before (dev-only option enabled everywhere)
app.Configure(iris.WithLiveReload)
// after
if isDev {
    app.Configure(iris.WithLiveReload)
}

if liveReloadEnabled && isProd() {
    log.Fatal("live reload must be disabled in production")
}
if ln, err := net.Listen("tcp", reloadAddr); err != nil {
    log.Fatalf("live reload port %s unavailable: %v", reloadAddr, err)
} else { ln.Close() }

if err := app.Build(); err != nil && strings.Contains(err.Error(), "inject live reload") {
    log.Printf("live reload unavailable (%v); continuing without it", err)
} else if err != nil {
    log.Fatal(err)
}

When it happens

Trigger: Enabling live reload features (e.g. via app configuration used by the iris-cli/dev flow) when the reload websocket/proxy cannot be set up — e.g. port conflict, invalid tunneling/reload config, or an error returned by injectLiveReload(app).

Common situations: Running behind a reverse proxy that blocks the reload route/port; another dev server already bound to the live-reload port; misconfigured Reload address in dev tooling; running in environments where the watcher cannot spawn.

Related errors

• build: %w
• build: view engine: %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/3ef29895c7a68412. Report an issue: GitHub.