microsoft/aspire · error · ArgumentException

Whole-number manifest field values must be between

Error message

Whole-number manifest field values must be between {long.MinValue} and {long.MaxValue}.

What it means

Whole-number floating-point field values are converted to long for exact JSON output; this error is thrown when the value is outside the long range (< long.MinValue or >= 2^63). The library refuses a lossy conversion instead of silently overflowing the JSON integer.

Solutions

Express the value in a smaller unit (e.g. Gi instead of bytes) so it fits in long
Use a string representation of the number if the Kubernetes field accepts strings (e.g. Quantity fields)
Validate the value against long.MinValue/long.MaxValue before passing and split or scale it

Example fix

// before
manifest.WithField("spec.capacity.storage", 10L * 1024 * 1024 * 1024 * 1024 * 1024 * 3); // overflows long
// after
manifest.WithField("spec.capacity.storage", "30Ti"); // Kubernetes quantity string

Defensive patterns

Strategy: validation

Validate before calling

if (value >= 9223372036854775808d || value < -9223372036854775808d) throw new InvalidOperationException("Whole-number field value exceeds long range.");

Type guard

static bool FitsInLong(double d) => Math.Truncate(d) == d && d >= long.MinValue && d < 9223372036854775808d;

Try / catch

try { manifest.WithField(path, value); } catch (ArgumentException ex) when (ex.Message.Contains("between")) { manifest.WithField(path, value.ToString(CultureInfo.InvariantCulture)); }

Prevention

Express large quantities in larger units (Gi/Ti) instead of raw bytes
Use Kubernetes Quantity strings for huge values
Check Math.Truncate(value) against long bounds before passing

When it happens

Trigger: Calling WithField with a float or double whose truncated value is >= 9223372036854775808 or < -9223372036854775808 — e.g. byte capacities expressed in bytes exceeding long range, or accidentally passing a value in the wrong unit.

Common situations: Specifying huge storage quantities in bytes instead of Gi, or computing large products (multiplied sizes/counts) that overflow long. Also occurs when double precision rounds a value up to exactly 2^63.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/a011f44b60161ac6. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesManifestResource.cs:206

        return value;
    }

    private static object NormalizeDecimalValue(decimal value)
    {
        if (decimal.Truncate(value) == value && value >= long.MinValue && value <= long.MaxValue)
        {
            return decimal.ToInt64(value);
        }

        return value;
    }

    private static long ConvertWholeNumberToLong(double value)
    {
        if (value < long.MinValue || value >= MaxLongExclusiveAsDouble)
        {
            throw new ArgumentException($"Whole-number manifest field values must be between {long.MinValue} and {long.MaxValue}.", nameof(value));
        }

        return (long)value;
    }

    private static object? NormalizeJsonNode(JsonNode node)
    {
        using var document = JsonDocument.Parse(node.ToJsonString());

        return NormalizeJsonElement(document.RootElement);
    }

    private static object? NormalizeJsonElement(JsonElement element)
    {
        return element.ValueKind switch
        {
            JsonValueKind.Null => null,
            JsonValueKind.String => element.GetString(),

View on GitHub (pinned to 25830f84bd)