flipped-aurora/gin-vue-admin · error

参数是必需的,且至少包含一个ID

Error message

 参数是必需的,且至少包含一个ID

What it means

requireNonEmptyList in server/mcp/org_common.go is the shared semantic validation for required ID-list parameters in the org toolset. It returns this error whenever the parsed []uint slice is empty, i.e. the list parameter was omitted, was not a valid array, or contained no usable IDs. The message interpolates the parameter name, so the actual text reads e.g. 'userIds 参数是必需的,且至少包含一个ID'.

Source

Thrown at server/mcp/org_common.go:262

		}
		// hint 仅是加速命中的优化;username 为 LIKE 模糊匹配且只查首页,未命中(名不匹配或
		// 命中过多致目标不在首页)时不误报,回退全量翻页扫描兜底
	}

	found, _, err := scanUsersByIDs(ctx, []uint{userID})
	if err != nil {
		return nil, err
	}
	if user, ok := found[userID]; ok {
		return &user, nil
	}
	return nil, fmt.Errorf("未找到 ID 为 %d 的用户(已扫描前 %d 条,大用户量场景请传 username 参数精确定位)", userID, orgUserScanMaxPages*orgUserScanPageSize)
}

// requireNonEmptyList 语义化的必填列表校验
func requireNonEmptyList(ids []uint, name string) error {
	if len(ids) == 0 {
		return errors.New(name + " 参数是必需的,且至少包含一个ID")
	}
	return nil
}

// parseOptionalPositiveInt 解析可选的正整数分页参数,兼容数字与字符串两种形式
// (与本工具集"数字参数兼容字符串"的既定设计一致);缺省或非法时返回 def
func parseOptionalPositiveInt(v any, def int) int {
	switch value := v.(type) {
	case float64:
		if value >= 1 {
			return int(value)
		}
	case string:
		if n, err := strconv.Atoi(strings.TrimSpace(value)); err == nil && n >= 1 {
			return n
		}
	}
	return def

View on GitHub (pinned to 3136500ef3)

Solutions

  1. Populate the list parameter with at least one positive integer ID
  2. Send the IDs as a JSON array of numbers (or numeric strings accepted by parseUintList), not a CSV string
  3. Verify upstream data actually contains the IDs you intend to pass (an empty source list means there is nothing to operate on)
  4. Read the parameter name embedded in the error message to confirm which list was empty

Example fix

// before
args := map[string]interface{}{ "userIds": []uint{} }
// after
args := map[string]interface{}{ "userIds": []uint{7, 9} }
Defensive patterns

Strategy: validation

Validate before calling

func validIDList(args map[string]interface{}, key string) ([]uint, error) {
  raw, ok := args[key].([]interface{})
  if !ok || len(raw) == 0 {
    return nil, fmt.Errorf("%s must be a non-empty array of IDs", key)
  }
  ids := make([]uint, 0, len(raw))
  for _, v := range raw {
    n, ok := toUint(v)
    if !ok || n == 0 {
      return nil, fmt.Errorf("%s contains an invalid ID: %v", key, v)
    }
    ids = append(ids, n)
  }
  return ids, nil
}

Type guard

func nonEmptyUintList(v interface{}) bool {
  l, ok := v.([]interface{})
  return ok && len(l) > 0
}

Try / catch

if err := requireNonEmptyList(ids, "userIds"); err != nil {
  return fmt.Errorf("nothing to operate on: %w", err)
}

Prevention

When it happens

Trigger: Calling any org MCP tool that takes a required ID list (e.g. userIds, deptIds for delete/batch operations) with an empty array []; omitting the list key entirely; passing a value that parseUintList failed to accept so the resulting slice is empty.

Common situations: Batch scripts that collected zero IDs due to an upstream filter returning nothing; clients sending {} or a comma-separated string instead of a JSON array of IDs; template-generated calls where the list placeholder was left empty.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of flipped-aurora/gin-vue-admin@3136500ef3 (2026-08-31). Data as JSON: /api/errors/4d419e44b77695c0. Report an issue: GitHub.