nsqio/nsq · error · http_api.Err

INVALID_ARG_CHANNEL

INVALID_ARG_CHANNEL

Error message

INVALID_ARG_CHANNEL

What it means

The channel value from the query string is validated with protocol.IsValidChannelName using the same rule as topics: ^[.a-zA-Z0-9_-]+(#ephemeral)?$ and 1..64 characters. Values that fail - including empty strings - return INVALID_ARG_CHANNEL and a 400 response from the HTTP handler.

Source

Thrown at internal/http_api/topic_channel_args.go:29

}

func GetTopicChannelArgs(rp getter) (string, string, error) {
	topicName, err := rp.Get("topic")
	if err != nil {
		return "", "", errors.New("MISSING_ARG_TOPIC")
	}

	if !protocol.IsValidTopicName(topicName) {
		return "", "", errors.New("INVALID_ARG_TOPIC")
	}

	channelName, err := rp.Get("channel")
	if err != nil {
		return "", "", errors.New("MISSING_ARG_CHANNEL")
	}

	if !protocol.IsValidChannelName(channelName) {
		return "", "", errors.New("INVALID_ARG_CHANNEL")
	}

	return topicName, channelName, nil
}

View on GitHub (pinned to 85cf10c09c)

Solutions

1. Use only [.a-zA-Z0-9_-] characters, 1-64 long, e.g. channel=archive.
2. Sanitize generated channel names at consumer-subscribe time in your client library.
3. Trim whitespace and reject empty strings before issuing the request.

Example fix

# before
curl -X POST 'http://127.0.0.1:4151/channel/create?topic=orders&channel=archive team'
# after
curl -X POST 'http://127.0.0.1:4151/channel/create?topic=orders&channel=archive_team'

var validTopicChannelNameRegex = regexp.MustCompile(`^[.a-zA-Z0-9_-]+(#ephemeral)?$`)

func isValidChannelName(name string) bool {
	return len(name) >= 1 && len(name) <= 64 && validTopicChannelNameRegex.MatchString(name)
}

if !isValidChannelName(channel) {
	return fmt.Errorf("invalid channel name %q", channel)
}

func isValidChannelName(name string) bool {
	return len(name) >= 1 && len(name) <= 64 && validTopicChannelNameRegex.MatchString(name)
}

if resp.StatusCode == 400 && strings.Contains(string(body), "INVALID_ARG_CHANNEL") {
	channel = sanitizeNSQName(channel)
	// note: subscribing to a new channel name starts a fresh stream - prefer fixing at the source
}

When it happens

Trigger: Passing channel= with an empty value (?topic=t&channel=), a channel containing spaces or slashes (channel=archive/2024), unicode, or a name longer than 64 characters. As with topics, the #ephemeral suffix is explicitly permitted.

Common situations: Auto-generating channel names per environment or customer without restricting the character set; passing a URL path fragment as channel; whitespace introduced by shell quoting or templating.

Related errors

• MISSING_ARG_TOPIC
• INVALID_ARG_TOPIC
• MISSING_ARG_CHANNEL
• address should not contain scheme
• --nsqd-http-address or --lookupd-http-address required

AI-assisted analysis of nsqio/nsq@85cf10c09c (2026-08-16). Data as JSON: /api/errors/5080f7c1f36f3486. Report an issue: GitHub.