What causes "build: %w" in kataras/iris?

Read the wrapped inner error — it originates from your OnBuild callback, not Iris itself.

build: %w

Error message

build: %w

What it means

iris.Application.Build runs the app's OnBuild hook and marks the app as built during server construction (New/NewServer/Run). If the user-supplied OnBuild callback returns an error, it is wrapped as "build: err". It means application-level build/registration logic provided by the user failed before the server could start.

Source

Thrown at iris.go:687

// It builds the default router with its default macros
// and the template functions that are very-closed to iris.
//
// If error occurred while building the Application, the returns type of error will be an *errgroup.Group
// which let the callers to inspect the errors and cause, usage:
//
// import "github.com/kataras/iris/v12/core/errgroup"
//
//	errgroup.Walk(app.Build(), func(typ any, err error) {
//		app.Logger().Errorf("%s: %s", typ, err)
//	})
func (app *Application) Build() error {
	if app.builded {
		return nil
	}

	if cb := app.OnBuild; cb != nil {
		if err := cb(); err != nil {
			return fmt.Errorf("build: %w", err)
		}
	}

	// start := time.Now()
	app.builded = true // even if fails.

	// check if a prior app.Logger().SetLevel called and if not
	// then set the defined configuration's log level.
	if app.logger.Level == golog.InfoLevel /* the default level */ {
		app.logger.SetLevel(app.config.LogLevel)
	}

	if app.defaultMode { // the app.I18n and app.View will be not available until Build.
		if !app.I18n.Loaded() {
			for _, s := range []string{"./locales/*/*", "./locales/*", "./translations"} {
				if _, err := os.Stat(s); err != nil {
					continue
				}

View on GitHub (pinned to 7bedaf55a0)

Solutions

Read the wrapped inner error — it originates from your OnBuild callback, not Iris itself.
Fix the failing logic inside your OnBuild function (check connections, config, registrations).
Add context to the error returned by OnBuild to pinpoint the failing step.
Note that app.builded is set even on failure; create a fresh app instance rather than retrying Build on the same one.

Example fix

// before
app.OnBuild = func() error { return db.Ping() } // opaque "build: ..."
// after
app.OnBuild = func() error {
    if err := db.Ping(); err != nil {
        return fmt.Errorf("onbuild: db ping failed: %w", err)
    }
    return nil
}

Defensive patterns

Strategy: try-catch

Try / catch

app.OnBuild = func() error {
    if err := setup(); err != nil {
        return fmt.Errorf("onbuild setup: %w", err)
    }
    return nil
}
if err := app.Build(); err != nil {
    var inner error
    if errors.As(err, &inner) {
        log.Printf("build hook failed: %v", inner)
    }
    os.Exit(1)
}

Prevention

Return descriptive errors from OnBuild — they're surfaced wrapped as "build: ...".
Keep OnBuild side effects idempotent; builded is set even on failure.
Do heavy dependency checks (DB, Redis) in OnBuild with clear error context.
Test startup in CI so hook failures surface before production.

When it happens

Trigger: Assigning app.OnBuild = func() error {...} whose callback returns an error; Build is then invoked automatically by New, NewServer, or Run, and the callback's error surfaces wrapped as "build: ...".

Common situations: OnBuild hooks doing dependency checks, config validation, or route/middleware registration that fail — e.g. DB ping failure, missing config, or an already-registered dependency — during app startup in main().

Related errors

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