elsa-workflows/elsa-core · error · FormatException

' ' is not a well-formed permission. Expected ' : '.

Error message

'{value}' is not a well-formed permission. Expected '{resource}:{verb}'.

What it means

Thrown by Permission.Parse (a validation guard wrapping TryParse) when the input string does not match the strict 'resource:verb' shape: empty or whitespace input, a missing separator, an empty resource or verb, or a second separator or path separator inside the verb all fail TryParse and cause Parse to throw. Use TryParse when malformed input is expected.

Solutions

Use Permission.TryParse and handle the false case instead of Parse
Correct the string to 'resource:verb' form
Split multi-permission strings correctly before parsing each element

Example fix

// before
var p = Permission.Parse("can-read");
// after
if (!Permission.TryParse("can-read", out var p))
    logger.LogWarning("Invalid permission: {P}", "can-read");

Defensive patterns

Strategy: validation

Validate before calling

if (!value.Contains(':')) throw new FormatException($"Permission '{value}' must be 'resource:verb'");
var parts = value.Split(':');
if (parts.Length != 2 || parts.Any(string.IsNullOrWhiteSpace)) throw new FormatException($"Invalid permission '{value}'");

Try / catch

try { var p = Permission.Parse(value); } catch (FormatException e) { logger.LogWarning(e, "Bad permission"); }

Prevention

Prefer TryParse over Parse for untrusted strings
Split multi-permission strings on the right separator before parsing
Centralize permission string constants to avoid typos

When it happens

Trigger: Calling Permission.Parse with strings like 'read', ':read', 'resource:', 'a:b:c', or containing whitespace/invalid characters.

Common situations: Hardcoded permission strings after renaming a resource or verb; configuration/claims carrying concatenated permission lists split incorrectly.

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 elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/8feb22a49ab803bf. Report an issue: GitHub.

Appendix: source

Thrown at src/common/Elsa.Api.Common/Authorization/Permission.cs:111

        var separator = trimmed.IndexOf(Separator);

        if (separator <= 0 || separator == trimmed.Length - 1)
            return false;

        var resource = trimmed[..separator];
        var verb = trimmed[(separator + 1)..];

        if (verb.IndexOf(Separator) >= 0 || verb.IndexOf(PathSeparator) >= 0)
            return false;

        permission = new(resource, verb);
        return true;
    }

    /// <summary>Parses <paramref name="value"/>, throwing when it is not a well-formed permission.</summary>
    public static Permission Parse(string value) =>
        TryParse(value, out var permission) ? permission : throw new FormatException($"'{value}' is not a well-formed permission. Expected '{{resource}}:{{verb}}'.");

    /// <inheritdoc />
    public override string ToString() => $"{Resource}{Separator}{Verb}";
}

View on GitHub (pinned to fe9217bdfa)