microsoft/aspire · error · ArgumentException

IAM role ARN ' ' is not in the expected form 'arn:aws:iam:…

Error message

IAM role ARN '{value}' is not in the expected form 'arn:aws:iam::<account>:role/<name>' (an optional path segment is allowed, e.g. 'arn:aws:iam::<account>:role/<path>/<name>').

What it means

ValidateIamRoleArn rejects IAM role ARN strings that do not match the expected AWS ARN shape 'arn:aws:iam::<account>:role/<name>' (an optional path segment like 'arn:aws:iam::<account>:role/<path>/<name>' is allowed). The Aspire Radius AWS cloud provider requires a well-formed role ARN to configure the credentials the Radius runtime will use, and it fails fast rather than emitting an invalid deployment. The account id must be exactly 12 digits.

Solutions

1. Copy the full role ARN exactly from the AWS IAM console (Roles → your role → ARN) and pass it unchanged.
2. Verify the ARN matches arn:aws:iam:<12-digit-account-id>:role/<name> or arn:aws:iam:<12-digit-account-id>:role/<path>/<name>.
3. If using a non-standard partition (govcloud/china), check whether the library's regex accepts it; otherwise transform the ARN to the expected aws partition form if your account allows.
4. Check for whitespace, quotes, or environment-variable interpolation artifacts in the value before it reaches the API.

Example fix

// before
.WithIrsa("arn:aws:iam::12345:role/my-role")
// after
.WithIrsa("arn:aws:iam::123456789012:role/my-role")

// C#
static bool IsValidIamRoleArn(string arn) =>
    System.Text.RegularExpressions.Regex.IsMatch(arn ?? "", @"^arn:aws:iam:\d{12}:role(/[\w.\-]+)*[\w.\-]+$");
// call before passing the ARN to the credential API
if (!IsValidIamRoleArn(roleArn)) throw new ArgumentException($"Bad role ARN: {roleArn}");

static bool IsIamRoleArn(object? v) => v is string s && s.StartsWith("arn:aws:iam:") && s.Contains(":role/");

try { builder.WithIrsa(roleArn); }
catch (ArgumentException ex) when (ex.ParamName == "roleArn") { logger.LogError(ex, "Invalid IAM role ARN supplied"); throw new InvalidOperationException("Fix the role ARN configuration", ex); }

When it happens

Trigger: Calling an AWS credential extension (e.g. aws.WithIrsa(...) or a role-based credential API) whose value argument is passed to CloudProviderValidation.ValidateIamRoleArn with a string that fails IamRoleArnPattern — malformed 'arn:' prefix, wrong service segment, non-12-digit account, missing '/role/' segment, or a role name containing characters outside the allowed set.

Common situations: Typo or truncation when pasting a role ARN from the AWS console; using an account id placeholder or short account number; confusing an IAM user ARN or instance-profile ARN with a role ARN; copying an ARN from a different partition (arn:aws-cn:, arn:aws-us-gov:) which the regex may reject; environment-variable-driven config supplying a stale value.

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

• AWS account ID ' ' must be exactly 12 digits.
• Unknown AWS credential type
• A recipe parameter on Radius environment
• ASPIRERADIUS011
• ASPIRERADIUS040

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

Appendix: source

Thrown at src/Aspire.Hosting.Radius/CloudProviders/CloudProviderValidation.cs:43

    internal static void ValidateNonEmpty(string value, string paramName)
        => ArgumentException.ThrowIfNullOrEmpty(value, paramName);

    internal static void ValidateAwsAccountId(string value, string paramName)
    {
        ArgumentException.ThrowIfNullOrEmpty(value, paramName);
        if (!AwsAccountIdPattern().IsMatch(value))
        {
            throw new ArgumentException(
                $"AWS account ID '{value}' must be exactly 12 digits.", paramName);
        }
    }

    internal static void ValidateIamRoleArn(string value, string paramName)
    {
        ArgumentException.ThrowIfNullOrEmpty(value, paramName);
        if (!IamRoleArnPattern().IsMatch(value))
        {
            throw new ArgumentException(
                $"IAM role ARN '{value}' is not in the expected form 'arn:aws:iam::<account>:role/<name>' (an optional path segment is allowed, e.g. 'arn:aws:iam::<account>:role/<path>/<name>').",
                paramName);
        }
    }

    [GeneratedRegex(@"^\d{12}$")]
    private static partial Regex AwsAccountIdPattern();

    // AWS IAM role ARNs may include a path between "role/" and the role name, e.g.
    // arn:aws:iam::123456789012:role/division/team/RDSAccess. Each segment (path
    // segments and the final role name) must be non-empty and may contain the
    // characters permitted in IAM friendly names; a trailing '/' or empty segment
    // is rejected. The character class is restricted to ASCII to avoid \w matching
    // non-ASCII word characters that AWS does not allow.
    // See https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names
    [GeneratedRegex(@"^arn:aws:iam::\d{12}:role/(?:[A-Za-z0-9+=,.@_-]+/)*[A-Za-z0-9+=,.@_-]+$")]
    private static partial Regex IamRoleArnPattern();
}

View on GitHub (pinned to 25830f84bd)