XTLS/Xray-core · error

duplicate ruleTag %s

Error message

duplicate ruleTag %s

What it means

A rule being added (initial load or reload) has a ruleTag that already exists in r.rules. Rule tags are the handle for RemoveRule/override operations, so uniqueness is enforced; on failure newly appended rules and opened webhooks are rolled back.

Source

Thrown at app/router/router.go:162

		}
		balancer.InjectContext(r.ctx)
		r.balancers[rule.Tag] = balancer
	}

	startIdx := len(r.rules)
	closeNewWebhooks := func() {
		for i := startIdx; i < len(r.rules); i++ {
			if r.rules[i].Webhook != nil {
				r.rules[i].Webhook.Close()
			}
		}
		r.rules = r.rules[:startIdx]
	}

	for _, rule := range config.Rule {
		if r.RuleExists(rule.GetRuleTag()) {
			closeNewWebhooks()
			return errors.New("duplicate ruleTag ", rule.GetRuleTag())
		}
		cond, err := rule.BuildCondition()
		if err != nil {
			closeNewWebhooks()
			return err
		}
		rr := &Rule{
			Condition: cond,
			Tag:       rule.GetTag(),
			RuleTag:   rule.GetRuleTag(),
		}
		if wh := rule.GetWebhook(); wh != nil {
			notifier, err := NewWebhookNotifier(wh)
			if err != nil {
				closeNewWebhooks()
				return err
			}
			rr.Webhook = notifier

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Remove or rename the conflicting ruleTag before adding
2. Call ListRule/RuleExists first and skip or update instead of duplicating
3. If replacing, send shouldAppend=false to rebuild the full rule set

Example fix

// before
AddRule(configWithRuleTag("rule-1"), true) // rule-1 already exists

// after
if r.RuleExists("rule-1") { r.RemoveRule("rule-1") }
AddRule(configWithRuleTag("rule-1"), true)

for _, r := range cfg.Rule {
    if existing.RuleExists(r.GetRuleTag()) {
        return fmt.Errorf("ruleTag %q already present; remove or rename first", r.GetRuleTag())
}

When it happens

Trigger: ReloadRules with shouldAppend=true re-submitting a rule whose ruleTag is already registered; initial config declaring the same ruleTag twice.

Common situations: Panels re-adding rules without checking RuleExists first; config merges producing duplicated entries.

Related errors

• duplicate balancer tag
• Routing statistics not enabled.
• this rule has no effective fields
• not a StrategyLeastLoadConfig
• unrecognized balancer type

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/3b1fdae3b30a16db. Report an issue: GitHub.