Humanizr/Humanizer · error · InvalidOperationException

'{path}' must define exactly one of phrase, sameRenderedAs,

Error message

'{path}' must define exactly one of phrase, sameRenderedAs, notApplicable, or unsupported.

What it means

Thrown when parsing a duration-case unit realization entry (under durationCases.realizations.units.<unit>) that does not contain exactly one of the four mutually-exclusive discriminator keys: phrase, sameRenderedAs, notApplicable, or unsupported. The generator builds a four-element boolean array from these keys and requires the count of enabled discriminators to be exactly 1, so both zero and two-or-more trigger the error.

Source

Thrown at src/Humanizer.SourceGenerators/Common/DurationCaseModels.cs:768

                throw new InvalidOperationException(
                    $"'{path}' contains an unresolved CLDR inheritance marker.");
            }

            var mapping = ExpectMapping(value, path);
            RejectUnknownKeys(
                mapping,
                path,
                ["phrase", "sameRenderedAs", "notApplicable", "unsupported", "provenance"]);
            var discriminators = new[]
            {
                mapping.TryGetValue("phrase", out _),
                mapping.GetScalar("sameRenderedAs") is not null,
                mapping.GetScalar("notApplicable") is not null,
                mapping.GetScalar("unsupported") is not null
            };
            if (discriminators.Count(static enabled => enabled) != 1)
            {
                throw new InvalidOperationException(
                    $"'{path}' must define exactly one of phrase, sameRenderedAs, notApplicable, or unsupported.");
            }

            if (mapping.TryGetValue("phrase", out var phraseValue))
            {
                var provenance = ParseProvenance(mapping, path, required: true);
                ValidateProvenance(provenance, sources, path);
                ValidateReachableMultipleForms(
                    phraseValue,
                    $"{path}.phrase",
                    requiredMultipleForms);
                var phrase = LocalePhraseNormalization.ParseTimeSpanPhrase(
                    phraseValue,
                    $"{path}.phrase",
                    preserveDuplicateForms: !requiredMultipleForms.IsEmpty);
                if (phrase.Single is null || phrase.Multiple?.Forms is null)
                {
                    throw new InvalidOperationException(

View on GitHub (pinned to ffc2b77c0f)

Solutions

Open the locale YAML at the path reported in the error and navigate to the indicated unit realization entry.
Ensure the entry contains exactly one of: phrase (a mapping), sameRenderedAs (scalar targeting another case), notApplicable (scalar reason), or unsupported (scalar reason).
Remove any extra discriminator keys so only one remains; if none is present, add the one matching the intended rendering strategy.
Rebuild to confirm the source generator accepts the entry.

Example fix

# before (zero discriminators)
second:
  provenance: [cldr]
# after
second:
  sameRenderedAs: nominative
  provenance: [cldr]

Defensive patterns

Strategy: validation

Validate before calling

# Before building, check each unit realization has exactly one discriminator
# PowerShell pre-build check (run from repo root)
$ErrorActionPreference = 'Stop'
$locales = Get-ChildItem src/Humanizer/Locales/*.yml
foreach ($f in $locales) {
    $yaml = Get-Content $f.FullName -Raw
    # crude regex: find realization unit blocks and count discriminators
    if ($yaml -match 'realizations:') {
        Write-Host "Checking $($f.Name) for discriminator validity..."
        # Full schema validation is recommended via a YAML parser
    }
}

Prevention

Keep a YAML schema or template for durationCases.realizations.units entries that shows exactly one discriminator per block.
Run a dotnet build after every locale edit to surface source-generator errors immediately.
Review the add-locale skill and contributing docs before authoring duration-case realizations.

When it happens

Trigger: A locale YAML unit realization block has no discriminator (e.g. only a 'provenance' key), or has more than one (e.g. both 'phrase' and 'sameRenderedAs', or 'notApplicable' and 'unsupported' on the same entry).

Common situations: A locale contributor adds a new unit realization and forgets to specify how it should be rendered, or copies an existing block and leaves both an old 'phrase' and a new 'notApplicable' when switching strategies. Also occurs when an author intends 'sameAsNominative' (a case-overlay concept) inside a realization block where it is not a valid discriminator.

Related errors

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