shadowsocks 2022 (multi-user): missing server method

Error message

shadowsocks 2022 (multi-user): missing server method

What it means

buildShadowsocks2022 handles the Shadowsocks-2022 server. When a 'users' array is present (multi-user or relay mode), the server-level cipher/method must be set explicitly because per-user methods are forbidden in 2022. An empty v.Cipher with non-empty users triggers this error.

Source

Thrown at infra/conf/shadowsocks.go:124

			Account: serial.ToTypedMessage(account),
		})
	}

	return config, nil
}

func buildShadowsocks2022(v *ShadowsocksServerConfig) (proto.Message, error) {
	if len(v.Users) == 0 {
		config := new(shadowsocks_2022.ServerConfig)
		config.Method = v.Cipher
		config.Key = v.Password
		config.Network = v.NetworkList.Build()
		config.Email = v.Email
		return config, nil
	}

	if v.Cipher == "" {
		return nil, errors.New("shadowsocks 2022 (multi-user): missing server method")
	}
	if !strings.Contains(v.Cipher, "aes") {
		return nil, errors.New("shadowsocks 2022 (multi-user): only blake3-aes-*-gcm methods are supported")
	}

	if v.Users[0].Address == nil {
		config := new(shadowsocks_2022.MultiUserServerConfig)
		config.Method = v.Cipher
		config.Key = v.Password
		config.Network = v.NetworkList.Build()

		config.Users = make([]*protocol.User, len(v.Users))
		processUser := func(idx int) error {
			user := v.Users[idx]
			if user.Cipher != "" {
				return errors.New("shadowsocks 2022 (multi-user): users must have empty method")
			}
			account := &shadowsocks_2022.Account{

View on GitHub (pinned to 7d214f8b09)

Solutions

Set the server-level method to a 2022 AES method, e.g. "2022-blake3-aes-128-gcm" or "2022-blake3-aes-256-gcm".
Match the key length to the method: 16-byte base64 key for aes-128, 32-byte for aes-256.
Keep per-user 'method' empty — only the server-level method is allowed in multi-user mode.

Example fix

// before
"settings": {"password": "...", "users": [{"password": "..."}]}

// after
"settings": {"method": "2022-blake3-aes-128-gcm", "password": "<16B-b64>", "users": [{"password": "<16B-b64>", "email": "u1"}]}

Defensive patterns

Strategy: validation

Validate before calling

func validSS2022MultiUser(method string, users []User) bool {
    return len(users) == 0 || method != ""
}

Prevention

Always emit the server-level method when generating multi-user 2022 configs

When it happens

Trigger: An inbound with 'users' defined but the top-level 'method'/'cipher' field omitted or empty, e.g. settings {"password": "...", "users": [...]} with no method.

Common situations: Assuming the 2022 method can be inferred from key length; converting a single-user 2022 config to multi-user and deleting the method field; tutorial configs that only show the single-user form.

Related errors

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