What causes "Invalid enumeration value" in dotnet/maui?

dotnet/maui · error · ArgumentException

Invalid enumeration value

Error message

Invalid enumeration value

What it means

SafeCopyFile switches on the SafeCopyFileOptions enum (PreserveOriginal, Overwrite, FindBetterName) and throws ArgumentException with paramName "options" if none of the known cases match. This guards against an undefined enum value, which in C# is only possible via an illegal cast from an out-of-range integer.

Source

Thrown at src/Compatibility/Core/src/WPF/Microsoft.Windows.Shell/Standard/Utilities.cs:325

					return null;
				case SafeCopyFileOptions.Overwrite:
					File.Copy(sourceFileName, destFileName, true);
					return destFileName;
				case SafeCopyFileOptions.FindBetterName:
					string directoryPart = Path.GetDirectoryName(destFileName);
					string fileNamePart = Path.GetFileNameWithoutExtension(destFileName);
					string extensionPart = Path.GetExtension(destFileName);
					foreach (string path in GenerateFileNames(directoryPart, fileNamePart, extensionPart))
					{
						if (!File.Exists(path))
						{
							File.Copy(sourceFileName, path);
							return path;
						}
					}
					return null;
			}
			throw new ArgumentException("Invalid enumeration value", "options");
		}

		/// <summary>
		/// Simple guard against the exceptions that File.Delete throws on null and empty strings.
		/// </summary>
		/// <param name="path">The path to delete.  Unlike File.Delete, this can be null or empty.</param>
		/// <remarks>
		/// Note that File.Delete, and by extension SafeDeleteFile, does not throw an exception
		/// if the file does not exist.
		/// </remarks>
		[SuppressMessage("Microsoft.Performance", "CA1811:AvoidUncalledPrivateCode")]
		public static void SafeDeleteFile(string path)
		{
			if (!string.IsNullOrEmpty(path))
			{
				File.Delete(path);
			}
		}

View on GitHub (pinned to f377ff1c5e)

Solutions

Validate the options value with Enum.IsDefined(typeof(SafeCopyFileOptions), options) before calling SafeCopyFile.
Map integer config inputs through an explicit switch that rejects unknown values.
If a new enum member is added, update the switch in SafeCopyFile to handle it.

Example fix

// before
Utilities.SafeCopyFile(src, dest, (SafeCopyFileOptions)configValue);

// after
if (!Enum.IsDefined(typeof(SafeCopyFileOptions), configValue))
{
    throw new ArgumentOutOfRangeException(nameof(configValue));
}
Utilities.SafeCopyFile(src, dest, (SafeCopyFileOptions)configValue);

Defensive patterns

Strategy: validation

Validate before calling

// Validate enum before calling SafeCopyFile
if (!Enum.IsDefined(typeof(SafeCopyFileOptions), options))
{
    throw new ArgumentOutOfRangeException(nameof(options), "Invalid SafeCopyFileOptions value.");
}
Utilities.SafeCopyFile(source, dest, options);

Prevention

Validate enum values from config or interop with Enum.IsDefined before use.
Map integer config inputs through an explicit, rejecting switch.
When adding a new enum member, update all switch statements that handle it.

When it happens

Trigger: Calling Utilities.SafeCopyFile(source, dest, options) where options is an undefined SafeCopyFileOptions value — e.g. (SafeCopyFileOptions)99. Reachable only through interop, deserialization, or arithmetic on the enum.

Common situations: Config-driven code that maps an integer config value to the enum without validation; deserializing SafeCopyFileOptions from JSON with an unknown numeric value; future enum members added without updating the switch.

Related errors

AI-assisted analysis of dotnet/maui@f377ff1c5e (2026-08-13). Data as JSON: /api/errors/ebc4d2fc523b5077. Report an issue: GitHub.