gorilla/mux · error

mux: route already has name %q, can't set %q

Error message

mux: route already has name %q, can't set %q

What it means

Set on r.err by Route.Name (route.go:212-216) when Name is called a second time on the same route. A route carries exactly one name (for URL building via Router.Get). Once r.err is set, later builder methods are no-ops and the route neither matches nor builds.

Source

Thrown at route.go:214

func (r *Route) GetHandlerWithMiddlewares() http.Handler {
	handler := r.handler

	if handler != nil && len(r.middlewares) > 0 {
		for i := len(r.middlewares) - 1; i >= 0; i-- {
			handler = r.middlewares[i].Middleware(handler)
		}
	}

	return handler
}

// Name -----------------------------------------------------------------------

// Name sets the name for the route, used to build URLs.
// It is an error to call Name more than once on a route.
func (r *Route) Name(name string) *Route {
	if r.name != "" {
		r.err = fmt.Errorf("mux: route already has name %q, can't set %q",
			r.name, name)
	}
	if r.err == nil {
		r.name = name
		r.namedRoutes[name] = r
	}
	return r
}

// GetName returns the name for the route, if any.
func (r *Route) GetName() string {
	return r.name
}

// ----------------------------------------------------------------------------
// Matchers
// ----------------------------------------------------------------------------

View on GitHub (pinned to db9d1d0073)

Solutions

1. Call Name exactly once per route.
2. If a helper already names the route, do not name it again at the call site.
3. Check route.GetError() after construction.

Example fix

// before
r.HandleFunc("/x", h).Name("x").Name("y")
// -> mux: route already has name "x", can't set "y"

// after
r.HandleFunc("/x", h).Name("x")

func setNameOnce(r *mux.Route, name string) error {
    if r.GetName() != "" { return errors.New("route already named") }
    r.Name(name)
    return nil
}

func isUnnamed(r *mux.Route) bool { return r != nil && r.GetName() == "" }

rt := r.HandleFunc("/x", h).Name("x")
if err := rt.GetError(); err != nil {
    log.Fatal(err)
}

When it happens

Trigger: r.HandleFunc("/x", h).Name("a").Name("b"), or chaining through a helper that calls Name and then the caller also calling Name on the returned route.

Common situations: A route-builder helper that names routes colliding with an outer .Name(); copy-paste leaving a stale Name; refactor moving Name into a wrapper while leaving the old call.

Related errors

• mux: duplicated route variable %q
• mux: number of parameters must be multiple of 2, got %v
• mux: path must start with a slash, got %q
• mux: number of parameters must be multiple of 2, got %v
• mux: missing name or pattern in %q

AI-assisted analysis of gorilla/mux@db9d1d0073 (2026-08-04). Data as JSON: /data/errors/73bf0167482c557c.json. Report an issue: GitHub.