What causes "{subject} references unknown source '{source}'." in Humanizr/Humanizer?

Add a matching source definition entry under the catalog's 'sources:' mapping with the referenced ID, including kind and locator.

Humanizr/Humanizer · error · InvalidOperationException

references unknown source ' '.

Error message

{subject} references unknown source '{source}'.

What it means

Every source ID referenced in an evidence block's 'sources:' list must be declared in the inflection catalog's top-level source definitions. This validator walks the sources array and rejects any ID not present in the known sourceIds set, preventing evidence from pointing at nonexistent provenance records.

Solutions

Add a matching source definition entry under the catalog's 'sources:' mapping with the referenced ID, including kind and locator.
Fix the typo in the evidence 'sources:' list to match an existing source ID exactly.
Remove the orphaned source reference from the evidence block if the source is no longer relevant.

Example fix

# before
sources:
  ud274:
    kind: 'treebank'
    locator: '...'
evidence:
  pluralize:
    sources: ['ud275']
# after
sources:
  ud274:
    kind: 'treebank'
    locator: '...'
evidence:
  pluralize:
    sources: ['ud274']

Defensive patterns

Strategy: validation

Validate before calling

# Before building, verify every referenced source ID exists in the sources mapping.
python3 -c "
import yaml, sys
for f in sys.argv[1:]:
    d = yaml.safe_load(open(f))
    infl = d.get('inflection',{})
    declared = set((infl.get('sources') or {}).keys())
    ev = infl.get('evidence',{})
    for direction in ('pluralize','singularize'):
        for src in (ev.get(direction,{}).get('sources') or []):
            if src not in declared:
                print(f'{f}: evidence {direction} references unknown source {src!r}')
" src/Humanizer/Locales/*.yml

Prevention

Maintain a single canonical source ID vocabulary and cross-reference it when editing evidence blocks.
When renaming a source ID, search-and-replace across all locale files to update references.
Add a pre-build CI step that validates source references against declared source definitions.

When it happens

Trigger: An evidence block (or any ValidateSources caller) lists a source string that does not match any key in the catalog's 'sources:' mapping. For example, evidence references 'ud2.15' but the sources section only defines 'ud2.14'.

Common situations: Renaming a source ID without updating all references. Copying an evidence block from another locale and forgetting to add the corresponding source definition. Typo in the source ID.

Related errors

AI-assisted analysis of Humanizr/Humanizer@ffc2b77c0f (2026-08-13). Data as JSON: /api/errors/5a4a3d3bd23f1f31. Report an issue: GitHub.

Appendix: source

Thrown at src/Humanizer.SourceGenerators/Generators/ProfileCatalogs/InflectionCatalogValidation.cs:103

            var correct = GetRequiredInt(values, "correct", $"Productive evidence '{direction}' must define correct");
            if (attempted < 100 || correct < 0 || correct > attempted ||
                correct * 100L < attempted * 99L)
            {
                throw new InvalidOperationException(
                    $"Productive evidence '{direction}' requires at least 100 attempts and 99% correctness.");
            }
        }

        static void ValidateSources(
            SimpleYamlMapping mapping,
            ImmutableHashSet<string> sourceIds,
            string subject)
        {
            foreach (var source in GetRequiredStrings(mapping, "sources", $"{subject} must define sources"))
            {
                if (!sourceIds.Contains(source))
                {
                    throw new InvalidOperationException($"{subject} references unknown source '{source}'.");
                }
            }
        }

        static void ValidateSourceDefinitions(SimpleYamlMapping sources)
        {
            foreach (var entry in sources.Values)
            {
                if (entry.Value is not SimpleYamlMapping source ||
                    source.GetScalar("kind") is not { Length: > 0 } ||
                    source.GetScalar("locator") is not { Length: > 0 })
                {
                    throw new InvalidOperationException(
                        $"Inflection source '{entry.Key}' must define non-empty kind and locator.");
                }

                ValidateProperties(
                    source,

View on GitHub (pinned to ffc2b77c0f)