chenhg5/cc-connect · error

cloud_web: gateway mode requires base_url for outbound send

Error message

cloud_web: gateway mode requires base_url for outbound send

What it means

An outbound message was sent through a cloud-web platform running in gateway mode, but no base_url is configured, so the transport has no upstream server to POST the message to. Gateway mode receives inbound events via its own listener; sending messages back still requires the address of the cloud-web server. This is a configuration error raised before any network I/O.

Source

Thrown at platform/cloud-web/gateway.go:265

		t.previewMu.Unlock()
		if ok {
			ch <- ack.PreviewHandle
		}
	case "capabilities_changed":
		var ch wireCapabilitiesChanged
		if err := json.Unmarshal(raw, &ch); err == nil && len(ch.Capabilities) > 0 {
			t.setCaps(capabilitySet(ch.Capabilities))
		}
	default:
		if t.onInbound != nil {
			t.onInbound(raw)
		}
	}
}

func (t *gatewayTransport) Send(ctx context.Context, msg map[string]any) error {
	if t.baseURL == "" {
		return fmt.Errorf("cloud_web: gateway mode requires base_url for outbound send")
	}
	body, err := json.Marshal(msg)
	if err != nil {
		return err
	}
	url := joinURL(t.baseURL, t.sendPath)
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
	if err != nil {
		return err
	}
	req.Header.Set("Content-Type", "application/json")
	authHTTP(req, t.token)
	resp, err := t.client.Do(req)
	if err != nil {
		return err
	}
	defer func() { _ = resp.Body.Close() }()
	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))

View on GitHub (pinned to 4000b2338a)

Solutions

1. Add base_url to the cloud-web platform section of config.toml pointing at the cloud-web server (e.g. "https://cloud.example.com").
2. If the deployment is intentionally receive-only, don't route outbound messages through this platform.
3. Restart cc-connect after adding the field; the value is read at transport construction.
4. Verify no stray whitespace-only value like base_url = " " — it is trimmed and still treated as empty.

Example fix

// config.toml — before
[[platform]]
name = "cloud-web"
mode = "gateway"
listen = ":8099"  # no base_url -> Send fails

// after
[[platform]]
name = "cloud-web"
mode = "gateway"
listen = ":8099"
base_url = "https://cloud.example.com"

// validate config before constructing the platform
if mode == "gateway" {
    if strings.TrimSpace(baseURL) == "" {
        return errors.New("cloud-web gateway mode requires a non-empty base_url for outbound send")
    }
    if u, err := url.Parse(baseURL); err != nil || u.Scheme == "" || u.Host == "" {
        return fmt.Errorf("invalid base_url %q", baseURL)
    }
}

if err := platform.Send(ctx, msg); err != nil {
    if strings.Contains(err.Error(), "requires base_url") {
        slog.Error("cloud-web gateway has no base_url; add it to config.toml and restart")
        return err
    }
    return err
}

When it happens

Trigger: Engine calls Send on the cloud-web platform while the platform section in config.toml omits base_url (or it is empty/whitespace) and mode is gateway.

Common situations: Config written for webhook-only inbound delivery without the outbound base_url field; base_url removed during a config refactor; environment-specific config file missing the field.

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

• acp: agent option "cmd" or "command" is required (path or na
• acp: command %q not found in PATH: %w
• claudecode: project dir not found
• resolve home directory: %w
• opencode: %q CLI not found in PATH, install from: https://gi

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