babalae/better-genshin-impact · error · InvalidOperationException

对象 {objectName} 缺少 template 配置

Error message

对象 {objectName} 缺少 template 配置

What it means

For a TemplateMatch-type object the loader must resolve a template image. ResolveTemplate throws InvalidOperationException when the template field is null or whitespace, because there is no image to match against. This is a configuration error, not a runtime/state problem.

Source

Thrown at BetterGenshinImpact/Core/Recognition/RecognitionObjectJsonLoader.cs:304

            {
                return Path.GetFileNameWithoutExtension(templateName);
            }

            return objectName;
        }

        private ImreadModes ParseTemplateMode(string? templateMode)
        {
            return string.IsNullOrWhiteSpace(templateMode)
                ? ImreadModes.Color
                : ParseEnumExact<ImreadModes>(templateMode, nameof(templateMode));
        }

        private string ResolveTemplate(string? template, string objectName)
        {
            if (string.IsNullOrWhiteSpace(template))
            {
                throw new InvalidOperationException($"对象 {objectName} 缺少 template 配置");
            }

            var resolved = template.Trim();
            while (resolved.StartsWith('@'))
            {
                var alias = resolved[1..];
                if (!_config.Templates.TryGetValue(alias, out resolved))
                {
                    throw new KeyNotFoundException($"未找到模板别名 {alias}");
                }
            }

            return resolved;
        }

        private Rect EvaluateRect(string expression)
        {
            var resolved = ResolveRegionExpression(expression);

View on GitHub (pinned to a7cb36712d)

Solutions

1. Add "template": "<filename or @alias>" to the object in Recognition.json.
2. If no template is intended, change the object type away from TemplateMatch (e.g. to a color-range or OCR recognizer).
3. Validate the JSON with a schema check that requires template for TemplateMatch objects before runtime.

Example fix

// before (Recognition.json)
// { "type": "TemplateMatch" }  -> throws: missing template

// after
// { "type": "TemplateMatch", "template": "btn_start.png" }

// schema-level check before runtime
foreach (var (name, cfg) in config.Objects)
{
    var t = cfg.Type?.Trim();
    if (string.Equals(t, "TemplateMatch", StringComparison.Ordinal)
        && string.IsNullOrWhiteSpace(cfg.Template))
        throw new InvalidOperationException($"Object '{name}' is TemplateMatch but has no template.");
}

try { return RecognitionObjectJsonLoader.Load(config, objectName, context); }
catch (InvalidOperationException ex) when (ex.Message.Contains("缺少 template 配置"))
{ Logger.LogError(ex, "TemplateMatch object missing template field."); throw; }

When it happens

Trigger: A RecognitionObject whose type is TemplateMatch has no template field, or it is set to an empty string, in Recognition.json.

Common situations: Copied an object and forgot to add template; changed type from a color/text recognizer to TemplateMatch without adding the field; field commented out.

Related errors

• 未找到名称为 {objectName} 的 RecognitionObject 配置
• 未找到模板别名 {alias}
• 表达式 {expression} 未返回 Rect
• 变量 {name} 存在循环引用
• {fieldName} 必须是 1 到 4 个数字

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