microsoft/aspire · error · ArgumentOutOfRangeException

Unknown persistent volume access mode.

Error message

Unknown persistent volume access mode.

What it means

Converting a PersistentVolumeAccessMode enum to its Kubernetes string representation hit a value outside the known set (ReadWriteOnce, ReadOnlyMany, ReadWriteMany, ReadWriteOncePod) and throws ArgumentOutOfRangeException. This guards against newer or invalid enum values the library doesn't yet map.

Solutions

  1. Only use the supported access modes: ReadWriteOnce, ReadOnlyMany, ReadWriteMany, ReadWriteOncePod
  2. Validate the enum value against the supported set before calling the API
  3. Upgrade the Aspire.Hosting.Kubernetes package to a version that maps your enum value

Example fix

// before
var mode = (PersistentVolumeAccessMode)int.Parse(rawMode); // may be unmapped
volume.WithAccessMode(mode);
// after
if (Enum.IsDefined(mode) && mode is PersistentVolumeAccessMode.ReadWriteOnce or PersistentVolumeAccessMode.ReadOnlyMany or PersistentVolumeAccessMode.ReadWriteMany or PersistentVolumeAccessMode.ReadWriteOncePod)
{
    volume.WithAccessMode(mode);
}
Defensive patterns

Strategy: validation

Validate before calling

static readonly PersistentVolumeAccessMode[] Supported = [PersistentVolumeAccessMode.ReadWriteOnce, PersistentVolumeAccessMode.ReadOnlyMany, PersistentVolumeAccessMode.ReadWriteMany, PersistentVolumeAccessMode.ReadWriteOncePod];
if (!Supported.Contains(accessMode)) throw new InvalidOperationException($"Access mode {accessMode} is not supported.");

Type guard

static bool IsSupportedAccessMode(PersistentVolumeAccessMode m) => m is PersistentVolumeAccessMode.ReadWriteOnce or PersistentVolumeAccessMode.ReadOnlyMany or PersistentVolumeAccessMode.ReadWriteMany or PersistentVolumeAccessMode.ReadWriteOncePod;

Try / catch

try { volume.WithAccessMode(accessMode); } catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "accessMode") { volume.WithAccessMode(PersistentVolumeAccessMode.ReadWriteOnce); }

Prevention

When it happens

Trigger: Passing a PersistentVolumeAccessMode value not in the four mapped members — possible with a newer enum version containing extra members, an invalid cast like (PersistentVolumeAccessMode)99, or a default/uninitialized enum of value 0 if 0 is unmapped.

Common situations: Upgrading the Aspire Kubernetes packages or a dependency that widened the enum before this library added mapping, or hand-rolling enum values from strings/ints parsed from YAML.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs:499

        // Generate is builder-bound because it needs the application name and the AppHost path hash,
        // so the candidate has to be built here even though the decision happens later.
        var environmentName = volume.Resource.Parent.Name.ToKubernetesResourceName();
        return VolumeNameGenerator.Generate(volume, $"kubernetes-{environmentName}");
    }

    /// <summary>
    /// Converts a <see cref="PersistentVolumeAccessMode"/> enum value to the
    /// Kubernetes API string representation.
    /// </summary>
    internal static string ToKubernetesString(this PersistentVolumeAccessMode accessMode)
    {
        return accessMode switch
        {
            PersistentVolumeAccessMode.ReadWriteOnce => "ReadWriteOnce",
            PersistentVolumeAccessMode.ReadOnlyMany => "ReadOnlyMany",
            PersistentVolumeAccessMode.ReadWriteMany => "ReadWriteMany",
            PersistentVolumeAccessMode.ReadWriteOncePod => "ReadWriteOncePod",
            _ => throw new ArgumentOutOfRangeException(nameof(accessMode), accessMode, "Unknown persistent volume access mode."),
        };
    }
}

View on GitHub (pinned to 25830f84bd)