'{colon[1]}' method doesn't exist in the controller {t.Name(

Error message

'{colon[1]}' method doesn't exist in the controller {t.Name()}

What it means

server/web/router.go:253: parseMappingMethods panics when the controller-side method name in a mapping segment does not resolve on the controller. After validating the HTTP method token, the router does reflectVal.MethodByName(colon[1]) on the controller value passed to web.Router; if the method does not exist (or is unexported, which MethodByName will not find), registration panics with "'{name}' method doesn't exist in the controller {Type}". The lookup is exact and case-sensitive.

Source

Thrown at server/web/router.go:253

		return methods
	}

	semi := strings.Split(mappingMethods[0], ";")
	for _, v := range semi {
		colon := strings.Split(v, ":")
		if len(colon) != 2 {
			panic("method mapping format is invalid")
		}
		comma := strings.Split(colon[0], ",")
		for _, m := range comma {
			if m != "*" && !HTTPMETHOD[strings.ToUpper(m)] {
				panic(v + " is an invalid method mapping. Method doesn't exist " + m)
			}
			if val := reflectVal.MethodByName(colon[1]); val.IsValid() {
				methods[strings.ToUpper(m)] = colon[1]
				continue
			}
			panic("'" + colon[1] + "' method doesn't exist in the controller " + t.Name())
		}
	}

	return methods
}

func (p *ControllerRegister) addRouterForMethod(route *ControllerInfo) {
	if len(route.methods) == 0 {
		for m := range HTTPMETHOD {
			p.addToRouter(m, route.pattern, route)
		}
		return
	}
	for k := range route.methods {
		if k != "*" {
			p.addToRouter(k, route.pattern, route)
			continue
		}

View on GitHub (pinned to 939cfde380)

Solutions

Match the mapping name exactly to an exported method on the controller: "get:List" requires func (c *ApiController) List().
Export the method (capitalize first letter) — unexported methods can never be mapped.
After refactors, grep the mapping strings for the old method name or compile a smoke test that registers all routes at startup.
Validate candidate mappings against reflect.ValueOf(c).MethodByName(name) before calling web.Router (see validationCode).

Example fix

// before
type ApiController struct{ web.Controller }
func (c *ApiController) List() { /* ... */ }
web.Router("/api", &ApiController{}, "get:Lists") // panic: Lists doesn't exist

// after
web.Router("/api", &ApiController{}, "get:List")

Defensive patterns

Strategy: validation

Validate before calling

// Verify each mapped controller method exists and is exported before web.Router
func mappingTargetsExist(c web.ControllerInterface, s string) error {
    v := reflect.ValueOf(c)
    for _, seg := range strings.Split(s, ";") {
        parts := strings.Split(seg, ":")
        if len(parts) != 2 {
            continue // format errors are handled by validation for error 275
        }
        name := parts[1]
        if !v.MethodByName(name).IsValid() {
            return fmt.Errorf("controller %T has no exported method %q", c, name)
        }
    }
    return nil
}

Try / catch

Go: validate before registration; if routes come from generated code, recover during registration and report the controller/method pair: defer func() { if r := recover(); r != nil { log.Fatalf("route for %T rejected: %v", c, r) } }()

Prevention

Keep mapping strings adjacent to the controller methods they name and rename both together.
Only exported methods can be mapped — capitalize the first letter.
Add a startup route-registration smoke test to every service.

When it happens

Trigger: web.Router("/api", &ApiController{}, "get:Lists") where the controller defines List, not Lists. Also mapping to an unexported method like "get:list" (reflection skips lowercase names), or renaming a controller method without updating the routing string.

Common situations: Rename refactors that miss the mapping string; plural/singular or case mismatches between route config and controller methods; mapping to methods defined on an embedded controller from another package that was refactored during a beego upgrade; generated routers referencing deleted handlers.

Related errors

AI-assisted analysis of beego/beego@939cfde380 (2026-08-15). Data as JSON: /api/errors/4ca8da2f933113f5. Report an issue: GitHub.