gofiber/fiber · error

datetime constraint requires a layout argument

Error message

datetime constraint requires a layout argument

What it means

Returned by datetimeConstraintType.Analyze (constraint.go:313-315) when a route parameter uses the datetime constraint but no layout argument was supplied. Analyze is called from newConstraint during route registration (constraint.go:187-191); a returned error simply leaves c.typedData empty, and Execute then returns false for every value — but Analyze's error is the canonical signal that the route declaration is malformed.

Solutions

1. Add a Go time layout argument to the constraint: "/:when<datetime(2006-01-02)>".
2. Use a layout constant and interpolate it consistently across routes that share a format.
3. If the parameter is free-form, drop the constraint entirely or switch to regex.
4. Add a route-registration test that exercises each constrained path with a valid sample.

Example fix

// before
app.Get("/:when<datetime>", handler) // missing layout

// after
app.Get("/:when<datetime(2006-01-02)>", handler)

// Validate the constraint declaration at route-registration time
func checkDatetimeLayout(arg string) error {
    if arg == "" { return errors.New("datetime constraint requires a layout argument") }
    return nil
}

// Route registration either succeeds or fails fast at startup; treat
// the Analyze error as a build-time signal by exercising the route in a test.
func TestRoutesRegister(t *testing.T) {
    app := fiber.New()
    register(app) // your route registration
    // If a datetime constraint lacks its layout, the route simply won't match;
    // assert expected matches/non-matches here.
}

When it happens

Trigger: Registering a route like app.Get("/:when<datetime>", ...) without the required layout argument. The datetime constraint needs the layout form, e.g. "/:when<datetime(2006-01-02)>"; omitting it leaves the constraint with no way to parse the parameter.

Common situations: Copy/paste from a route that used minLen (which requires a number) into datetime without updating the argument; reading docs that omitted the argument; refactoring a route and dropping the parenthesized argument.

Related errors

• len constraint requires an argument
• maxLen constraint requires an argument
• minLen constraint requires an argument
• parse constraint arg
• add: invalid http method

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

Appendix: source

Thrown at constraint.go:314

	}
	return true
}

type guidConstraintType struct{}

func (guidConstraintType) Name() string { return ConstraintGUID }
func (guidConstraintType) Execute(param string, _ []any) bool {
	_, err := uuid.Parse(param)
	return err == nil
}

type datetimeConstraintType struct{}

func (datetimeConstraintType) Name() string { return ConstraintDatetime }
func (datetimeConstraintType) Analyze(args []string) ([]any, error) {
	args = parseConstraintArgs(args)
	if len(args) == 0 {
		return nil, errors.New("datetime constraint requires a layout argument")
	}
	return []any{args[0]}, nil
}

func (datetimeConstraintType) Execute(param string, data []any) bool {
	if len(data) == 0 {
		return false
	}
	layout, ok := data[0].(string)
	if !ok || layout == "" {
		return false
	}
	_, err := time.Parse(layout, param)
	return err == nil
}

type minLenConstraintType struct{}

View on GitHub (pinned to a105acad6c)