XTLS/Xray-core · error

handler not found: ${tag}

Error message

handler not found: ${tag}

What it means

Error "handler not found: ${tag}" thrown in XTLS/Xray-core.

Source

Thrown at app/proxyman/inbound/inbound.go:67

	} else {
		m.untaggedHandlers = append(m.untaggedHandlers, handler)
	}

	if m.running {
		return handler.Start()
	}

	return nil
}

// GetHandler implements inbound.Manager.
func (m *Manager) GetHandler(ctx context.Context, tag string) (inbound.Handler, error) {
	m.access.RLock()
	defer m.access.RUnlock()

	handler, found := m.taggedHandlers[tag]
	if !found {
		return nil, errors.New("handler not found: ", tag)
	}
	return handler, nil
}

// RemoveHandler implements inbound.Manager.
func (m *Manager) RemoveHandler(ctx context.Context, tag string) error {
	if tag == "" {
		return common.ErrNoClue
	}

	m.access.Lock()
	defer m.access.Unlock()

	if handler, found := m.taggedHandlers[tag]; found {
		if err := handler.Close(); err != nil {
			errors.LogWarningInner(ctx, err, "failed to close handler ", tag)
		}
		delete(m.taggedHandlers, tag)

View on GitHub (pinned to 7d214f8b09)

When it happens

Trigger: Thrown at app/proxyman/inbound/inbound.go:67 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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