chenhg5/cc-connect · error

cloud_web: public_url is required when register_url is set f

Error message

cloud_web: public_url is required when register_url is set for gateway transport

What it means

In gateway transport with webhook registration, the platform must expose a publicly reachable URL so the service can call back into it. New enforces that when register_url is provided, public_url must also be provided, otherwise registration would produce a webhook the service cannot reach.

Source

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

		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
}

func pickInt(v any) int {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Add public_url to the gateway config with a publicly reachable HTTPS URL for this instance
2. Restart or re-run a tunnel (e.g. cloudflared) and update public_url with the new address
3. If no public URL is possible, switch transport to "long_poll" or "websocket", which do not require register_url/public_url

Example fix

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

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

if strings.TrimSpace(cfg.RegisterURL) != "" && strings.TrimSpace(cfg.PublicURL) == "" {
    return fmt.Errorf("cloud_web: public_url must accompany register_url")
}

When it happens

Trigger: Calling New with transport = "gateway", a non-empty register_url, and an empty/whitespace public_url.

Common situations: Self-hosted deployments behind NAT or localhost where the admin set the register endpoint but no public hostname; tunnel (ngrok/cloudflared) URL not updated after a restart; forgetting public_url when migrating from long_poll to gateway transport.

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

• cloud_web: base_url or register_url is required for gateway
• cloud_web: token is required
• cloud_web: transport must be websocket, long_poll, or gatewa
• cloud_web: ws_url or base_url is required for websocket tran
• cloud_web: base_url is required for long_poll transport

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