XTLS/Xray-core · error · errors.Error

failed to get dispatcher for geodata downloader

Error message

failed to get dispatcher for geodata downloader

What it means

Thrown during geodata Instance creation when core.RequireFeatures cannot resolve a routing.Dispatcher on the instance. The downloader needs the dispatcher to dial through a tagged outbound, so without it the component cannot start; the original RequireFeatures error is chained.

Source

Thrown at app/geodata/geodata.go:38

	mu      sync.Mutex
	running bool
}

func New(ctx context.Context, config *Config) (*Instance, error) {
	if config.Cron == "" {
		return &Instance{}, nil
	}

	g := &Instance{
		assets: config.Assets,
	}

	if len(g.assets) > 0 {
		var dispatcher routing.Dispatcher
		if err := core.RequireFeatures(ctx, func(d routing.Dispatcher) {
			dispatcher = d
		}); err != nil {
			return nil, errors.New("failed to get dispatcher for geodata downloader").Base(err)
		}
		g.downloader = newDownloader(ctx, dispatcher, config.Outbound)
	}

	g.tasker = cron.New(
		cron.WithChain(cron.SkipIfStillRunning(cron.DiscardLogger)),
		cron.WithLogger(cron.DiscardLogger),
	)
	if _, err := g.tasker.AddFunc(config.Cron, g.execute); err != nil {
		return nil, errors.New("invalid geodata cron").Base(err)
	}
	errors.LogInfo(ctx, "scheduled geodata reload with cron: ", config.Cron)

	return g, nil
}

func (g *Instance) execute() {
	var err error

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Ensure app/router (which provides routing.Dispatcher) is registered in the instance features before geodata is created
2. Run via the standard xray binary/config pipeline, which registers features in the correct order
3. If geodata auto-update is not needed, clear the geodata assets list so the dispatcher requirement is skipped

// When embedding Xray-core, register the router app before creating geodata:
// (order matters — RequireFeatures resolves lazily but the feature must be
// registered with the instance)
instance := core.New(config) // ensure config includes app/router
// then start geodata; dispatcher feature will resolve

When it happens

Trigger: Config declares geodata assets (len(config.Assets) > 0) but the core instance being built has no routing/dispatcher feature registered yet — e.g. feature registration order is wrong, or geodata is initialized in a stripped-down instance that lacks app/router.

Common situations: Embedding Xray-core as a library and calling New() before registering router features; custom builds that omit the router app; startup-order regressions after a version upgrade.

Related errors

• Unable to locate a fake DNS Engine
• connection idle timeout
• cannot understand address
• cannot dial remote address
• cannot finish connection

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