XTLS/Xray-core · error

failed to use decryption

Error message

failed to use decryption

What it means

Thrown while constructing a VLESS inbound whose config.Decryption is set to something other than "" or "none". In that case an encryption.ServerInstance is initialized from base64url key segments (Decryption split on '.'), plus XorMode, SecondsFrom, SecondsTo and Padding. If that Init fails (bad key material, malformed parameters), this error wraps the cause.

Source

Thrown at proxy/vless/inbound/inbound.go:113

		policyManager:          v.GetFeature(policy.ManagerType()).(policy.Manager),
		stats:                  v.GetFeature(stats.ManagerType()).(stats.Manager),
		validator:              validator,
		outboundHandlerManager: v.GetFeature(outbound.ManagerType()).(outbound.Manager),
		observer:               v.GetFeature(extension.ObservatoryType()),
		defaultDispatcher:      v.GetFeature(routing.DispatcherType()).(routing.Dispatcher),
		ctx:                    ctx,
	}

	if config.Decryption != "" && config.Decryption != "none" {
		s := strings.Split(config.Decryption, ".")
		var nfsSKeysBytes [][]byte
		for _, r := range s {
			b, _ := base64.RawURLEncoding.DecodeString(r)
			nfsSKeysBytes = append(nfsSKeysBytes, b)
		}
		handler.decryption = &encryption.ServerInstance{}
		if err := handler.decryption.Init(nfsSKeysBytes, config.XorMode, config.SecondsFrom, config.SecondsTo, config.Padding); err != nil {
			return nil, errors.New("failed to use decryption").Base(err).AtError()
		}
	}

	if config.Fallbacks != nil {
		handler.fallbacks = make(map[string]map[string]map[string]*Fallback)
		// handler.regexps = make(map[string]*regexp.Regexp)
		for _, fb := range config.Fallbacks {
			if handler.fallbacks[fb.Name] == nil {
				handler.fallbacks[fb.Name] = make(map[string]map[string]*Fallback)
			}
			if handler.fallbacks[fb.Name][fb.Alpn] == nil {
				handler.fallbacks[fb.Name][fb.Alpn] = make(map[string]*Fallback)
			}
			handler.fallbacks[fb.Name][fb.Alpn][fb.Path] = fb
			/*
				if fb.Path != "" {
					if r, err := regexp.Compile(fb.Path); err != nil {
						return nil, errors.New("invalid path regexp").Base(err).AtError()

View on GitHub (pinned to 7d214f8b09)

Solutions

  1. If you do not intend VLESS encryption, set "decryption": "none" (or omit it) — this is the standard VLESS setting
  2. If you do use it, verify each dot-separated segment is valid raw-base64url and decodes to the expected key length
  3. Check XorMode and the SecondsFrom < SecondsTo window and Padding values against the peer's configuration
  4. Read the wrapped Init error for the exact rejected parameter

Example fix

// before
"decryption": "ss-2022-blake3-aes-256-gcm.dGVzdA"

// after (standard VLESS, no extra encryption at protocol level)
"decryption": "none"
Defensive patterns

Strategy: validation

Validate before calling

// keep standard VLESS unless you truly need protocol-level encryption
func normalizeDecryption(d string) string {
    if d == "" { return "none" }
    return d
}
// if using encryption keys, pre-validate each segment:
func validKeySegments(dec string) bool {
    for _, seg := range strings.Split(dec, ".") {
        b, err := base64.RawURLEncoding.DecodeString(seg)
        if err != nil || len(b) == 0 { return false }
    }
    return true
}

Try / catch

if err := handlerCreate(...); err != nil && strings.Contains(err.Error(), "failed to use decryption") {
    log.Printf("VLESS decryption config rejected: %v — falling back to 'none' is not automatic; fix config", err)
}

Prevention

When it happens

Trigger: Setting "decryption" in a VLESS inbound to a non-"none" value whose dotted base64url key segments are invalid (wrong length after RawURLEncoding decode, empty segments), or supplying inconsistent XorMode/SecondsFrom/SecondsTo/Padding values.

Common situations: Copying an encryption-style decryption string from another deployment without the matching keys; typos in the base64url key; using standard base64 (+//) instead of raw URL encoding (-_ , no padding); clients/servers from versions with incompatible encryption parameters.

Related errors

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