dotnetcore/CAP · error · ArgumentOutOfRangeException

origin character string length must between 1~256!

Error message

origin character string length must between 1~256!

What it means

SNS topic names are limited to 256 characters, so NormalizeForAws validates the length before sanitizing '.' and ':' characters. Passing a string longer than 256 characters throws ArgumentOutOfRangeException naming the origin parameter.

Solutions

1. Shorten the CAP topic name so it is at most 256 characters
2. Use the TopicName prefix/shortening strategies: move versioning into message headers instead of the topic name
3. Choose a different transport (e.g. RabbitMQ/Kafka) if long names are a hard requirement, or alias short names
4. Add a startup validation rule that asserts all configured topic names are <= 256 chars before subscribing

Example fix

// before
services.AddCap(x => { x.ProducerTopics = new[] { "mycompany.production.paymentservice.invoice.generated.v1.final" + longSuffix }; });
// after
services.AddCap(x => { x.ProducerTopics = new[] { "invoice-generated-v1" }; }); // <= 256 chars, no '.'/':'

if (origin is null || origin.Length is < 1 or > 256) throw new ArgumentOutOfRangeException(nameof(origin), "AWS topic name must be 1-256 characters");

bool IsValidAwsTopicName(string? s) => !string.IsNullOrEmpty(s) && s.Length <= 256;

try { var name = origin.NormalizeForAws(); } catch (ArgumentOutOfRangeException ex) { logger.LogError(ex, "Topic name exceeds AWS 256-char limit"); throw; }

When it happens

Trigger: Publishing or subscribing to a CAP topic whose name (after transport prefixing) exceeds 256 characters, then hitting the SQS/SNS transport which normalizes the name via NormalizeForAws.

Common situations: Very long, namespaced topic names (e.g. company.environment.service.event.version concatenated) that exceed the AWS limit; also long cloud environment prefixes producing names valid in RabbitMQ/Kafka but invalid in AWS.

Related errors

• Specified argument was out of the range of valid values…
• Value cannot be null. (Parameter 'topicNames')
• Value cannot be null. (Parameter 'topics')
• Value cannot be null. (Parameter 'configure')
• Value cannot be null. (Parameter 'options')

AI-assisted analysis of dotnetcore/CAP@e52b8508e5 (2026-09-14). Data as JSON: /api/errors/74424658f4d0b247. Report an issue: GitHub.

Appendix: source

Thrown at src/DotNetCore.CAP.AmazonSQS/TopicNormalizer.cs:13

// Copyright (c) .NET Core Community. All rights reserved.
// Licensed under the MIT License. See License.txt in the project root for license information.

using System;

namespace DotNetCore.CAP.AmazonSQS;

internal static class TopicNormalizer
{
    public static string NormalizeForAws(this string origin)
    {
        if (origin.Length > 256)
            throw new ArgumentOutOfRangeException(nameof(origin) + " character string length must between 1~256!");
        return origin.Replace(".", "-").Replace(":", "_");
    }
}

View on GitHub (pinned to e52b8508e5)