What causes "create service" in XTLS/Xray-core?

Generate a key of the right size: xray uuid won't do it — use `openssl rand -base64 32` for aes-256/chacha20 methods, `openssl rand -base64 16` (wait: 16 raw bytes) for 128-bit methods — verify the decoded byte length matches the method.

XTLS/Xray-core · error

create service

Error message

create service

What it means

Wrapper around shadowaead_2022.NewServiceWithPassword failing for a single-user 2022 inbound. The underlying library rejects method/password combinations — most often the base64-decoded key length does not match the method (16 bytes for aes-128, 32 for aes-256/chacha20 variants). The inbound cannot start.

Source

Thrown at proxy/shadowsocks_2022/inbound.go:59

func NewServer(ctx context.Context, config *ServerConfig) (*Inbound, error) {
	networks := config.Network
	if len(networks) == 0 {
		networks = []net.Network{
			net.Network_TCP,
			net.Network_UDP,
		}
	}
	inbound := &Inbound{
		networks: networks,
		email:    config.Email,
		level:    int(config.Level),
	}
	if !C.Contains(shadowaead_2022.List, config.Method) {
		return nil, errors.New("unsupported method ", config.Method)
	}
	service, err := shadowaead_2022.NewServiceWithPassword(config.Method, config.Key, 500, inbound, nil)
	if err != nil {
		return nil, errors.New("create service").Base(err)
	}
	inbound.service = service
	return inbound, nil
}

func (i *Inbound) Network() []net.Network {
	return i.networks
}

func (i *Inbound) Process(ctx context.Context, network net.Network, connection stat.Connection, dispatcher routing.Dispatcher) error {
	inbound := session.InboundFromContext(ctx)
	inbound.Name = "shadowsocks-2022"
	inbound.CanSpliceCopy = 3

	var metadata M.Metadata
	if inbound.Source.IsValid() {
		metadata.Source = M.ParseSocksaddr(inbound.Source.NetAddr())
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

Generate a key of the right size: xray uuid won't do it — use `openssl rand -base64 32` for aes-256/chacha20 methods, `openssl rand -base64 16` (wait: 16 raw bytes) for 128-bit methods — verify the decoded byte length matches the method.
Match client and server keys exactly after fixing length.
Check the base error in the log to confirm which constraint failed.

Example fix

# before: 24-byte key with a 256-bit method
"password": "$(openssl rand -base64 24)"
# after: 32-byte key for 2022-blake3-aes-256-gcm
"password": "$(openssl rand -base64 32)"

Defensive patterns

Strategy: validation

Validate before calling

func validateSS2022Key(method, keyB64 string) error {
  raw, err := base64.StdEncoding.DecodeString(keyB64)
  if err != nil { return err }
  want := 32
  if strings.Contains(method, "128") { want = 16 }
  if len(raw) != want { return fmt.Errorf("key is %d bytes, method %q needs %d", len(raw), method, want) }
  return nil
}

Type guard

func hasValidKeyLength(method string, keyLen int) bool {
  if strings.Contains(method, "128") { return keyLen == 16 }
  return keyLen == 32
}

Try / catch

service, err := shadowaead_2022.NewServiceWithPassword(method, key, 500, inbound, nil)
if err != nil {
  return fmt.Errorf("2022 service init failed (check key length for %s): %w", method, err)
}

Prevention

Always generate keys with openssl rand -base64 (32 or 16) matched to the method.
Automate key generation in provisioning scripts instead of letting users type passwords.

When it happens

Trigger: config.Key is not valid base64 of the exact length required by config.Method (e.g. 24-byte random string with 2022-blake3-aes-256-gcm, or raw binary), or method/password key-derivation constraints violated inside the 2022 library.

Common situations: Using a human-chosen password instead of a generated base64 key; generating keys of the wrong bit size (openssl rand -base64 24 vs 32); switching method without regenerating the key.

Related errors

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