ory/hydra · warning

user_code is required

Error message

user_code is required

What it means

Returned by POSTdevice when the submitted form contains an empty user_code field. The device-flow verification handler requires the user-visible code entered by the user; its absence means the form was submitted without it, independent of the device_challenge value.

Source

Thrown at cmd/cmd_perform_device_flow.go:180

	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
	}

	// Accept the user code with a hand-rolled request instead of the generated
	// client: other modules in this repository compile this package against the
	// released hydra-client-go/v2 module, which predates the device
	// authorization API.
	cfg := s.cl.GetConfig()
	if len(cfg.Servers) == 0 {
		http.Error(w, "No Hydra endpoint is configured", http.StatusInternalServerError)
		return
	}
	acceptURL := strings.TrimSuffix(cfg.Servers[0].URL, "/") +
		"/admin/oauth2/auth/requests/device/accept?device_challenge=" + url.QueryEscape(challenge)

View on GitHub (pinned to 4174065ffb)

Solutions

1. Include the user_code form field with the code displayed by the CLI/device flow
2. Check the form input's name attribute is exactly user_code
3. Prompt the user to re-enter the code if left blank
4. Use verification_uri_complete so the code is pre-filled

Example fix

// before
curl -X POST http://localhost:4445/device -d 'device_challenge=abc'
// after
curl -X POST http://localhost:4445/device -d 'user_code=1234&device_challenge=abc'

// client side: check before submitting
if not user_code:
    raise ValueError("user_code is required before submitting the device form")

When it happens

Trigger: Submitting the device verification form with an empty user_code field, or a client omitting the user_code form key entirely.

Common situations: User leaving the code field blank and submitting; automation posting only device_challenge; form field name mismatch (e.g. 'code' instead of 'user_code').

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• device_challenge is required
• errKeyNotFound
• Invalid action
• Failed to render template: %s
• Failed to parse form: %s

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