elsa-workflows/elsa-core · error · InvalidOperationException

The configured application instance name from

Error message

The configured application instance name from {source} contains invalid characters. Use only letters, numbers, periods, hyphens, or underscores, and start and end the value with a letter or number. (optionally joined with) The configured application instance name from {source} is {instanceName.Length} characters long, but it must be {ConfiguredInstanceNameMaxLength} characters or fewer. The value is used to create per-instance transport entities such as '{instanceName}{TriggerChangeTokenSignalEndpointNameSuffix}', which must fit within Azure Service Bus's {AzureServiceBusSubscriptionNameMaxLength}-character subscription name limit.

What it means

ConfiguredApplicationInstanceNameProvider resolves a stable per-instance name used to build per-instance transport entities (such as the Azure Service Bus change-token subscription). ResolveConfiguredInstanceName throws InvalidOperationException when the configured name contains characters outside [A-Za-z0-9._-], or does not start/end with an alphanumeric character (a too-long name alone is auto-shortened, but invalid characters are fatal). The message combines both errors when they co-occur.

Solutions

1. Sanitize the configured instance name: keep only letters, digits, periods, hyphens, underscores, and ensure it starts and ends with a letter or digit (e.g., 'worker-node-01').
2. Check the instance-name environment variable and any configuration source feeding it; strip or replace illegal characters in your deployment script/Helm chart.
3. If the value comes from a hostname or metadata service, transform it before configuring Elsa (e.g., replace '/' with '-').

Example fix

// before (env var)
ELSA_INSTANCE_NAME="worker/01!"
// after
ELSA_INSTANCE_NAME="worker-01"

static bool IsValidInstanceName(string? name) =>
    !string.IsNullOrWhiteSpace(name) &&
    char.IsAsciiLetterOrDigit(name[0]) &&
    char.IsAsciiLetterOrDigit(name[^1]) &&
    name.All(c => char.IsAsciiLetterOrDigit(c) || c is '.' or '-' or '_');
// call before configuring: IsValidInstanceName(Environment.GetEnvironmentVariable("ELSA_INSTANCE_NAME"))

string? SanitizeInstanceName(string? raw) =>
    string.IsNullOrWhiteSpace(raw) ? null :
    new string(raw.Trim().Select(c => char.IsAsciiLetterOrDigit(c) || c is '.' or '-' or '_' ? c : '-').ToArray()).Trim('.','-','_');

try
{
    var name = instanceNameProvider.GetName();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("instance name"))
{
    logger.LogCritical(ex, "Invalid configured instance name; fix the environment variable/configuration");
    throw; // fail fast: misconfigured transport entities
}

When it happens

Trigger: A name supplied from configuration or the instance-name environment variable fails IsValidConfiguredInstanceName: it is empty after trim, contains spaces, slashes, '@', ':', or other non [A-Za-z0-9._-] characters, or begins/ends with a separator like '-' or '_'. If it is also longer than ConfiguredInstanceNameMaxLength, the length error is appended to the same exception.

Common situations: Setting the instance-name env var to a pod FQDN or container ID containing dots is fine, but values derived from hostnames with underscores at the end, Kubernetes downward-API strings with slashes, or copy-pasted names with trailing whitespace/special chars trip the check. Deployment scripts injecting 'pod/name' or GUIDs with braces are typical culprits.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• The OpenID Connect connection configuration is invalid.
• Adapter settings migrations must define an adapter type and…
• Configuration connection
• The configured secret binding is invalid.
• Runtime entity definition name is required.

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/a71b2fb604a2867c. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.Hosting.Management/Services/ConfiguredApplicationInstanceNameProvider.cs:93

        var isTooLong = instanceName.Length > ConfiguredInstanceNameMaxLength;
        var hasInvalidCharacters = !IsValidConfiguredInstanceName(instanceName);

        if (hasInvalidCharacters)
        {
            var errors = new List<string>
            {
                $"The configured application instance name from {source} contains invalid characters. " +
                "Use only letters, numbers, periods, hyphens, or underscores, and start and end the value with a letter or number."
            };

            if (isTooLong)
            {
                errors.Add(
                    $"The configured application instance name from {source} is {instanceName.Length} characters long, but it must be {ConfiguredInstanceNameMaxLength} characters or fewer. " +
                    $"The value is used to create per-instance transport entities such as '{instanceName}{TriggerChangeTokenSignalEndpointNameSuffix}', which must fit within Azure Service Bus's {AzureServiceBusSubscriptionNameMaxLength}-character subscription name limit.");
            }

            throw new InvalidOperationException(string.Join(" ", errors));
        }

        if (!isTooLong)
            return instanceName;

        var shortenedName = ShortenConfiguredInstanceName(instanceName);

        logger.LogWarning(
            "The configured application instance name from {Source} is {Length} characters long, exceeding the {MaxLength}-character limit required for Azure Service Bus transport entities. " +
            "Using deterministic shortened instance name '{ShortenedName}' instead.",
            source,
            instanceName.Length,
            ConfiguredInstanceNameMaxLength,
            shortenedName);

        return shortenedName;
    }

View on GitHub (pinned to fe9217bdfa)