XTLS/Xray-core · error

unknown config id:

Error message

unknown config id: 

What it means

Returned by ConfigCreatorCache.CreateConfig when asked to instantiate a config whose inbound/outbound protocol id is not in the creator registry. Protocol creators register themselves by name (vless, vmess, trojan, etc.); an unregistered id means either a typo'd protocol name or a protocol whose package was not compiled/registered into this binary. Note this is distinct from the 'already registered' duplicate-registration error in the same cache.

Source

Thrown at infra/conf/loader.go:26

)

type ConfigCreator func() interface{}

type ConfigCreatorCache map[string]ConfigCreator

func (v ConfigCreatorCache) RegisterCreator(id string, creator ConfigCreator) error {
	if _, found := v[id]; found {
		return errors.New(id, " already registered.").AtError()
	}

	v[id] = creator
	return nil
}

func (v ConfigCreatorCache) CreateConfig(id string) (interface{}, error) {
	creator, found := v[id]
	if !found {
		return nil, errors.New("unknown config id: ", id)
	}
	return creator(), nil
}

type JSONConfigLoader struct {
	cache     ConfigCreatorCache
	idKey     string
	configKey string
}

func NewJSONConfigLoader(cache ConfigCreatorCache, idKey string, configKey string) *JSONConfigLoader {
	return &JSONConfigLoader{
		idKey:     idKey,
		configKey: configKey,
		cache:     cache,
	}
}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Correct the protocol name to one supported by this Xray build (vless, vmess, trojan, shadowsocks, socks, http, freedom, blackhole, wireguard, hysteria, ...)
2. Verify case and trim whitespace in the protocol field
3. If the protocol genuinely exists in Xray but fails, your binary may lack that module — use a full official build

Example fix

// before
{ "protocol": "socks5", "settings": {} }
// after
{ "protocol": "socks", "settings": {} }

// Validate protocol against the supported set before creating config
var supportedProtocols = map[string]bool{
	"vless": true, "vmess": true, "trojan": true, "shadowsocks": true,
	"socks": true, "http": true, "freedom": true, "blackhole": true,
	"wireguard": true, "hysteria": true, "loopback": true,
}
if !supportedProtocols[strings.ToLower(protocolName)] {
	return fmt.Errorf("unsupported protocol %q", protocolName)
}

func isSupportedProtocol(p string) bool {
	_, ok := supportedProtocols[strings.ToLower(strings.TrimSpace(p))]
	return ok
}

When it happens

Trigger: Setting an inbound or outbound protocol string to an unsupported or misspelled value, e.g. "vmes", "socks5" (should be socks), "shadowsocks " with trailing space, or a protocol that exists only in a fork build. Also triggered programmatically by calling CreateConfig with an id never registered via RegisterCreator.

Common situations: Copy-pasting configs between Xray forks (e.g. sing-box protocol names like 'hysteria2' where Xray expects 'hysteria'); using a minimal build without certain protocols compiled in; whitespace/case mistakes in the protocol field.

Related errors

• ${idKey} not found in JSON context
• socks 4 is not allowed when auth is required.
• unknown Socks version: {version}
• unable to create log handler for
• failed to get outbound handler with tag: ${tag}

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