new route: %s conflicts with an already registered one: %s r

Error message

new route: %s conflicts with an already registered one: %s route

What it means

When registering a route whose path pattern matches an already-registered route (and both are considered equal by DeepEqual), the router checks the RouteRegisterRule. With rule == RouteError the registration is rejected with this error instead of silently replacing or overlapping the existing route.

Source

Thrown at core/router/api_builder.go:122

				repo.routes = append(cp, repo.routes[i+1:]...)
			}

			delete(repo.paths, r.tmpl.Src)
			return true
		}
	}
	return false
}

func (repo *repository) register(route *Route, rule RouteRegisterRule) (*Route, error) {
	for i, r := range repo.routes {
		// 14 August 2019 allow register same path pattern with different macro functions,
		// see #1058
		if route.DeepEqual(r) {
			if rule == RouteSkip {
				return r, nil
			} else if rule == RouteError {
				return nil, fmt.Errorf("new route: %s conflicts with an already registered one: %s route", route.String(), r.String())
			} else if rule == RouteOverlap {
				overlapRoute(r, route)
				return route, nil
			} else {
				// replace existing with the latest one, the default behavior.
				repo.routes = append(repo.routes[:i], repo.routes[i+1:]...)
			}

			break // continue
		}
	}

	repo.routes = append(repo.routes, route)

	if route.StatusCode == 0 { // a common resource route, not a status code error handler.
		if repo.paths == nil {
			repo.paths = make(map[string]*Route)
		}

View on GitHub (pinned to 7bedaf55a0)

Solutions

Remove or rename the duplicate route registration (change method or path)
Change the register rule to iris.RouteOverlap or iris.RouteSkip or the default RouteReplace if the duplicate is intentional
Guard registrations with a check on whether the route already exists before calling Handle
Consolidate route setup into a single location to avoid double registration

Example fix

// before
app.SetRegisterRule(iris.RouteError)
app.Get("/users", listUsers)
app.Get("/users", listUsers) // panics-free error at build
// after
app.Get("/users", listUsers)
app.Get("/users/{id:uint}", getUser)

Defensive patterns

Strategy: validation

Validate before calling

func routeExists(app *iris.Application, method, path string) bool {
    for _, r := range app.Routes() {
        if r.Method == method && r.Path == path { return true }
    }
    return false
}

Try / catch

_, err := app.Handle(method, path, handler)
if err != nil && strings.Contains(err.Error(), "conflicts with an already registered one") {
    log.Fatalf("duplicate route: %v", err)
}

Prevention

Keep all route registrations in one place or one package
Use distinct paths/methods for handlers with the same name
Only use iris.RouteError rule when you want strict duplicate detection
Run integration tests that build the app so duplicates fail in CI

When it happens

Trigger: Calling app.Handle/PartyHandle twice with the exact same method + path pattern (same static path, same parameters and same macro functions) while iris.RouteError register rule is configured via app.SetRegisterRule(iris.RouteError).

Common situations: Copy-pasting route registrations across refactors; registering the same endpoint in two init/setup functions; middleware or plugin code re-registering a route; switching the register rule to RouteError to surface accidental duplicates.

Related errors

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/c86747aac31090a0. Report an issue: GitHub.