{"record":{"id":"a71b2fb604a2867c","repo":"elsa-workflows/elsa-core","slug":"the-configured-application-instance-name-from-source","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.Hosting.Management/Services/ConfiguredApplicationInstanceNameProvider.cs","lineNumber":93,"sourceCode":"        var isTooLong = instanceName.Length > ConfiguredInstanceNameMaxLength;\n        var hasInvalidCharacters = !IsValidConfiguredInstanceName(instanceName);\n\n        if (hasInvalidCharacters)\n        {\n            var errors = new List<string>\n            {\n                $\"The configured application instance name from {source} contains invalid characters. \" +\n                \"Use only letters, numbers, periods, hyphens, or underscores, and start and end the value with a letter or number.\"\n            };\n\n            if (isTooLong)\n            {\n                errors.Add(\n                    $\"The configured application instance name from {source} is {instanceName.Length} characters long, but it must be {ConfiguredInstanceNameMaxLength} characters or fewer. \" +\n                    $\"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.\");\n            }\n\n            throw new InvalidOperationException(string.Join(\" \", errors));\n        }\n\n        if (!isTooLong)\n            return instanceName;\n\n        var shortenedName = ShortenConfiguredInstanceName(instanceName);\n\n        logger.LogWarning(\n            \"The configured application instance name from {Source} is {Length} characters long, exceeding the {MaxLength}-character limit required for Azure Service Bus transport entities. \" +\n            \"Using deterministic shortened instance name '{ShortenedName}' instead.\",\n            source,\n            instanceName.Length,\n            ConfiguredInstanceNameMaxLength,\n            shortenedName);\n\n        return shortenedName;\n    }\n","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.Hosting.Management/Services/ConfiguredApplicationInstanceNameProvider.cs#L75-L111","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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').","Check the instance-name environment variable and any configuration source feeding it; strip or replace illegal characters in your deployment script/Helm chart.","If the value comes from a hostname or metadata service, transform it before configuring Elsa (e.g., replace '/' with '-')."],"exampleFix":"// before (env var)\nELSA_INSTANCE_NAME=\"worker/01!\"\n// after\nELSA_INSTANCE_NAME=\"worker-01\"","handlingStrategy":"validation","validationCode":"static bool IsValidInstanceName(string? name) =>\n    !string.IsNullOrWhiteSpace(name) &&\n    char.IsAsciiLetterOrDigit(name[0]) &&\n    char.IsAsciiLetterOrDigit(name[^1]) &&\n    name.All(c => char.IsAsciiLetterOrDigit(c) || c is '.' or '-' or '_');\n// call before configuring: IsValidInstanceName(Environment.GetEnvironmentVariable(\"ELSA_INSTANCE_NAME\"))","typeGuard":"string? SanitizeInstanceName(string? raw) =>\n    string.IsNullOrWhiteSpace(raw) ? null :\n    new string(raw.Trim().Select(c => char.IsAsciiLetterOrDigit(c) || c is '.' or '-' or '_' ? c : '-').ToArray()).Trim('.','-','_');","tryCatchPattern":"try\n{\n    var name = instanceNameProvider.GetName();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"instance name\"))\n{\n    logger.LogCritical(ex, \"Invalid configured instance name; fix the environment variable/configuration\");\n    throw; // fail fast: misconfigured transport entities\n}","preventionTips":["Validate the instance-name value in CI/deployment templates before rollout.","Derive instance names from safe sources (pod name sanitized, not full FQDN with slashes).","Keep names alphanumeric-delimited and well under the max length."],"tags":["configuration","validation","azure-service-bus","naming"],"backgroundTag":"invalid-identifier-format","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}