stride3d/stride · error · FormatException

The string does not match the expected format.

Error message

The string does not match the expected format.

What it means

BaseConverter.ConvertFromString parses components of the form 'Name:Value' by splitting each component on ':'. A component that does not yield exactly two parts is rejected with a FormatException. The library expects structured 'field:value' pairs for the target struct.

Solutions

  1. Ensure each component is exactly 'FieldName:Value' with one colon separator
  2. Escape or avoid ':' inside values; pre-check input with a regex like ^[A-Za-z_][A-Za-z0-9_]*:[^:]+$ per component
  3. Catch FormatException and surface a descriptive message to the user
  4. Verify the value part parses via the inner converter before assignment

Example fix

// before
ConvertFromString("X1.0, Y2.0")
// after
ConvertFromString("X:1.0, Y:2.0")
Defensive patterns

Strategy: validation

Validate before calling

static readonly Regex Comp = new("^[^:]+:[^:]+$");
bool ok = input.Split(',').All(c => Comp.IsMatch(c.Trim()));

Try / catch

try { value = converter.ConvertFromString(context, culture, s); }
catch (FormatException ex) { /* show expected 'Name:Value' format */ }

Prevention

When it happens

Trigger: Calling ConvertFromString (or a TypeConverter.ConvertFrom with a string) where a component lacks the ':' separator, e.g. 'X' instead of 'X:1.0', or a component containing multiple colons producing more than 2 parts.

Common situations: Hand-edited property strings in editors/configs; localized input where users omit the field name; nested values that themselves contain ':' (e.g. times or URLs) accidentally breaking the split.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/15d1adc4d0111e77. Report an issue: GitHub.

Appendix: source

Thrown at sources/core/Stride.Core.Design/TypeConverters/BaseConverter.cs:123

    }

    protected TResult? ConvertFromString<TResult, T>(ITypeDescriptorContext? context, CultureInfo? culture, string str) where TResult : new()
    {
        if (string.IsNullOrEmpty(str))
            return default;

        culture ??= CultureInfo.CurrentCulture;

        var converter = TypeDescriptor.GetConverter(typeof(T));
        var strings = str.Trim().Split(' ', StringSplitOptions.RemoveEmptyEntries);

        // Note: we explicitly box the struct so we can use reflection to set values.
        object result = new TResult();
        foreach (var comp in strings)
        {
            var split = comp.Split(':');
            if (split.Length != 2)
                throw new FormatException("The string does not match the expected format.");
            var property = Properties.Cast<FieldPropertyDescriptor>().First(x => x.Name == split[0]);
            var compValue = converter.ConvertFromString(context, culture, split[1]);
            property.FieldInfo.SetValue(result, compValue);
        }
        return (TResult)result;
    }

    /// <summary>
    /// Returns whether this converter can convert an object of the given type to the type of this converter, using the specified context.
    /// </summary>
    /// <param name="context">An <see cref="T:System.ComponentModel.ITypeDescriptorContext"/> that provides a format context.</param>
    /// <param name="sourceType">A <see cref="T:System.Type"/> that represents the type you want to convert from.</param>
    /// <returns>
    /// true if this converter can perform the conversion; otherwise, false.
    /// </returns>
    public override bool CanConvertFrom(ITypeDescriptorContext? context, Type sourceType)
    {
        return sourceType == typeof(string) || base.CanConvertFrom(context, sourceType);

View on GitHub (pinned to 96fad776d2)