cloud_web: base_url or register_url is required for gateway

Error message

cloud_web: base_url or register_url is required for gateway transport

What it means

For the "gateway" transport, the constructor needs either a base_url or a register_url to know where the cloud-web service lives. If, after attempting to derive base_url from register_url, both are still empty, New returns this error. Gateway mode cannot start without knowing the service endpoint.

Source

Thrown at platform/cloud-web/cloudweb.go:116

	var tp transport
	switch transportKind {
	case "websocket":
		resolved := resolveWSURL(baseURL, wsURL)
		if strings.TrimSpace(resolved) == "" {
			return nil, fmt.Errorf("cloud_web: ws_url or base_url is required for websocket transport")
		}
		tp = newWSTransport(resolved, token, name, project)
	case "long_poll":
		if strings.TrimSpace(baseURL) == "" {
			return nil, fmt.Errorf("cloud_web: base_url is required for long_poll transport")
		}
		tp = newPollTransport(baseURL, token, name, project, eventsPath, sendPath, longPollMS)
	case "gateway":
		if strings.TrimSpace(baseURL) == "" && strings.TrimSpace(registerURL) != "" {
			baseURL = deriveBaseURL(registerURL)
		}
		if strings.TrimSpace(baseURL) == "" && strings.TrimSpace(registerURL) == "" {
			return nil, fmt.Errorf("cloud_web: base_url or register_url is required for gateway transport")
		}
		if strings.TrimSpace(registerURL) != "" && strings.TrimSpace(publicURL) == "" {
			return nil, fmt.Errorf("cloud_web: public_url is required when register_url is set for gateway transport")
		}
		tp = newGatewayTransport(baseURL, token, name, project, listen, webhookPath, registerURL, publicURL, sendPath)
	}

	return &Platform{
		name:           name,
		project:        project,
		token:          token,
		transportKind:  transportKind,
		allowFrom:      allowFrom,
		shareInChannel: shareInChannel,
		groupReplyAll:  groupReplyAll,
		tp:             tp,
		replyCtxs:      make(map[string]string),
	}, nil

View on GitHub (pinned to 4000b2338a)

Solutions

Set register_url (e.g. "https://cloud.example.com/webhook/register") so base_url can be derived automatically
Or set base_url directly to the cloud-web service root URL
Ensure at least one of the two fields is non-empty after trimming whitespace
Check for config key renames/typos (register_url vs registerUrl) causing the value to not load

Example fix

// before
[platform.cloud_web]
transport = "gateway"

// after
[platform.cloud_web]
transport = "gateway"
register_url = "https://cloud.example.com/webhook/register"
public_url = "https://public.example.com"

Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(cfg.Transport) == "gateway" && strings.TrimSpace(cfg.BaseURL) == "" && strings.TrimSpace(cfg.RegisterURL) == "" {
    return fmt.Errorf("cloud_web: gateway needs base_url or register_url")
}

Prevention

Prefer setting register_url and letting base_url derive from it
Validate gateway configs before deploying to headless environments
Document per-transport required fields in config.example.toml

When it happens

Trigger: Constructing the cloud_web platform with transport = "gateway" while both base_url and register_url are empty or whitespace-only in the platform options.

Common situations: A fresh gateway config where the user set transport = "gateway" but forgot both endpoint fields; a templated config where the register_url placeholder was never filled; renaming config keys during a version upgrade so the old url key is no longer read.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/2d72040f3d80490a. Report an issue: GitHub.