babalae/better-genshin-impact · error · ArgumentException

多角色接口需要字符串集合或 JS Array，单个字符串请使用 GetCharacter。

Error message

多角色接口需要字符串集合或 JS Array，单个字符串请使用 GetCharacter。

What it means

Thrown by ParseCharacterNames (called from GetMultiCharacters) when the characterNames argument is a single string rather than a collection. GetMultiCharacters is designed for multiple characters and accepts string collections or JS Arrays; a single string should use GetCharacter instead. This is an argument-type contract violation.

Source

Thrown at BetterGenshinImpact/GameTask/CharacterDevelopment/CharacterDevelopmentTask.cs:122

    /// <summary>
    /// 获取多个角色的信息。兼容 C# 字符串集合以及实现 <see cref="IList"/> 的 ClearScript JS Array。
    /// </summary>
    /// <param name="characterNames">目标角色名集合。</param>
    /// <param name="categories">使用分号分隔的分类：属性、武器、天赋；null 表示全部。</param>
    public async Task<List<CharacterDevelopmentResult>> GetMultiCharacters(object characterNames, string? categories = null)
    {
        var names = ParseCharacterNames(characterNames);
        var categoryFlags = ParseCategories(categories);
        return await new CharacterDevelopmentStateMachineTask(names, categoryFlags)
            .Start(CancellationContext.Instance.Cts.Token);
    }

    internal static List<string> ParseCharacterNames(object characterNames)
    {
        ArgumentNullException.ThrowIfNull(characterNames);
        if (characterNames is string)
        {
            throw new ArgumentException("多角色接口需要字符串集合或 JS Array，单个字符串请使用 GetCharacter。", nameof(characterNames));
        }

        if (characterNames is not IEnumerable enumerable)
        {
            throw new ArgumentException("角色名参数必须是字符串集合或 JS Array。", nameof(characterNames));
        }

        List<string> names = [];
        foreach (var item in enumerable)
        {
            if (item is not string name)
            {
                throw new ArgumentException("角色名集合中的每个元素都必须是字符串。", nameof(characterNames));
            }

            names.Add(NormalizeCharacterName(name));
        }

View on GitHub (pinned to a7cb36712d)

Solutions

1. Use GetCharacter(characterName) for a single character instead of GetMultiCharacters.
2. If using GetMultiCharacters, wrap the name in an array: ['CharacterName'].
3. From JavaScript, ensure you pass an Array (e.g. ['钟离']) not a bare string.

Example fix

// before (wrong)
await dev.GetMultiCharacters('钟离');
// after (single character)
await dev.GetCharacter('钟离');
// after (multi-character API with array)
await dev.GetMultiCharacters(['钟离']);

// Before calling GetMultiCharacters, check the argument type
if (characterNames is string)
{
    // Use GetCharacter for a single string
    return await task.GetCharacter((string)characterNames);
}
if (characterNames is not IEnumerable)
{
    throw new ArgumentException("characterNames must be a string collection or JS Array.");
}

static bool IsCharacterNameCollection(object obj)
{
    return obj is not string && obj is IEnumerable;
}

try
{
    await dev.GetMultiCharacters(names);
}
catch (ArgumentException ex) when (ex.Message.Contains("多角色接口"))
{
    // Switch to GetCharacter or wrap in an array
}

When it happens

Trigger: Called from GetMultiCharacters(characterNames, categories) → ParseCharacterNames(characterNames). characterNames is of runtime type string (e.g. passed from JS as a plain string instead of an array).

Common situations: JavaScript caller passes a single character name string instead of wrapping it in an array; C# caller mistakenly passes a string to the multi-character API; confusion between GetCharacter (single) and GetMultiCharacters (plural).

Related errors

• 角色名参数必须是字符串集合或 JS Array。
• 角色名集合中的每个元素都必须是字符串。
• 角色名集合不能为空。
• 角色名不能为空。
• 读取分类不能为空字符串。

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/0960634ef4fbb6e0. Report an issue: GitHub.