gofiber/fiber · error

failed to execute

Error message

failed to execute: %w

What it means

Returned on the fallback branch of DefaultRes.Render() after a template parsed successfully but failed during tmpl.Execute(). Execution errors come from the data model, not the grammar: the template tried to evaluate an index, call a method, or range over a value that does not satisfy it.

Solutions

1. Read the wrapped error — html/template names the field/method and the template line.
2. Align the bind struct/map keys with the template's dotted access paths.
3. Ensure methods invoked from templates return either one value or (value, error).
4. For ranges, confirm the bind value is a slice, array, or map; for index access, confirm it is a map or a pointer to a struct with that field.

Example fix

// before — template expects .Address.City but bind has no Address
type User struct{ Name string }
return c.Render("user.gohtml", User{Name: "Ada"})
// user.gohtml: {{ .Address.City }}
// -> failed to execute: template: ...: Address is not a field of struct ...

// after
type User struct{ Name string; Address struct{ City string } }
return c.Render("user.gohtml", User{Name: "Ada", Address: struct{ City string }{"London"}})

// Execute templates against representative bind values in tests.
func validateExecute(path string, bind any) error {
    t, err := template.ParseFiles(path)
    if err != nil { return err }
    return t.Execute(io.Discard, bind)
}

// Ensure bind is a type the template was authored against.
func isAcceptableBind(b any) bool {
    switch b.(type) {
    case fiber.Map, nil:
        return true
    }
    v := reflect.ValueOf(b)
    return v.Kind() == reflect.Struct || v.Kind() == reflect.Ptr && v.Elem().Kind() == reflect.Struct || v.Kind() == reflect.Map
}

if err := c.Render(file, bind); err != nil {
    if strings.Contains(err.Error(), "failed to execute") {
        log.Printf("template execution mismatch for %s: %v", file, err)
        return fiber.ErrInternalServerError
    }
    return err
}

When it happens

Trigger: Calling ctx.Render(name, bind) with app.config.Views nil, where the parsed template references a field/method/type that bind does not provide: {{ .Address.City }} when bind has no Address; calling a method that returns two values where template expects one; ranging over a non-map/non-slice; a custom function that panics.

Common situations: Renaming a struct field without updating the template; passing fiber.Map with the wrong keys; passing a value of a different type than the template was written against; template calls a func that returns (T, error) — html/template disallows two-value methods unless the second is error.

Related errors

• failed to parse
• ErrUnknownTag
• failed to open
• failed to read
• failed to render

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/2c2d12ea6bc8c11d. Report an issue: GitHub.

Appendix: source

Thrown at res.go:949

			}
		}
	}

	if !rendered {
		// Render raw template using 'name' as filepath if no engine is set
		var tmpl *template.Template
		if _, err := readContent(buf, name); err != nil {
			return err
		}
		// Parse template
		tmpl, err := template.New("").Parse(rootApp.toString(buf.Bytes()))
		if err != nil {
			return fmt.Errorf("failed to parse: %w", err)
		}
		buf.Reset()
		// Render template
		if err := tmpl.Execute(buf, bind); err != nil {
			return fmt.Errorf("failed to execute: %w", err)
		}
	}

	response := &r.c.fasthttp.Response

	// Set Content-Type to text/html
	response.Header.SetContentType(MIMETextHTMLCharsetUTF8)
	// Set rendered template to body
	response.SetBody(buf.Bytes())

	return nil
}

func (r *DefaultRes) renderExtensions(bind any) {
	r.c.renderExtensions(bind)
}

// Send sets the HTTP response body without copying it.

View on GitHub (pinned to a105acad6c)