ory/hydra · error

Failed to render template: %s

Error message

Failed to render template: %s

What it means

GETdevice renders the user-code HTML page via userCodeTemplate.Execute directly into the ResponseWriter. If template execution fails (e.g. a custom template referenced a missing field), the handler writes a 500 with the template error message.

Source

Thrown at cmd/cmd_perform_device_flow.go:168

	mux *http.ServeMux
}

func (s *deviceSrv) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	s.mux.ServeHTTP(w, r)
}

func (s *deviceSrv) GETdevice(w http.ResponseWriter, r *http.Request) {
	if r.URL.Query().Get("device_challenge") == "" {
		http.Error(w, "device_challenge is required", http.StatusBadRequest)
		return
	}

	err := userCodeTemplate.Execute(w, userCodeData{
		UserCode:        r.URL.Query().Get("user_code"),
		DeviceChallenge: r.URL.Query().Get("device_challenge"),
	})
	if err != nil {
		http.Error(w, fmt.Sprintf("Failed to render template: %s", err), http.StatusInternalServerError)
		return
	}
}

func (s *deviceSrv) POSTdevice(w http.ResponseWriter, r *http.Request) {
	if err := r.ParseForm(); err != nil {
		http.Error(w, fmt.Sprintf("Failed to parse form: %s", err), http.StatusBadRequest)
		return
	}
	userCode, challenge := r.FormValue("user_code"), r.FormValue("device_challenge")
	if userCode == "" {
		http.Error(w, "user_code is required", http.StatusBadRequest)
		return
	}
	if challenge == "" {
		http.Error(w, "device_challenge is required", http.StatusBadRequest)
		return
	}

View on GitHub (pinned to 4174065ffb)

Solutions

1. Restore or fix the custom template so it only references fields on userCodeData (user_code, device_challenge)
2. Validate the template parses (template.Must) at startup to fail fast
3. Check server logs for the exact template error printed in the 500 body
4. Fall back to the built-in template to verify the handler itself is healthy

Example fix

// before
tmpl := template.Must(template.New("usercode").Parse(userTpl))
// after
tmpl, err := template.New("usercode").Parse(userTpl)
if err != nil {
	log.Fatalf("invalid user code template: %v", err)
}

// validate template at startup, not at request time
var userCodeTemplate = template.Must(template.New("usercode").Parse(defaultTpl))

if err != nil {
	log.Printf("user code template render failed: %v", err)
	http.Error(w, "failed to render page", http.StatusInternalServerError)
	return
}

When it happens

Trigger: userCodeTemplate.Execute returns an error while writing the user_code/device_challenge data — typically a broken or incompatible custom template passed in place of the built-in one.

Common situations: Overriding the default template with one referencing fields not in userCodeData; template syntax errors introduced by customization; ResponseWriter failing mid-write (client disconnect).

Related errors

• device_challenge is required
• Failed to parse form: %s
• user_code is required
• errKeyNotFound
• http(s) loader disabled

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/2d40220912ad7e1f. Report an issue: GitHub.