chenhg5/cc-connect · error

max: start webhook: %w

Error message

max: start webhook: %w

What it means

Wraps any error returned by startWebhook when the platform is configured with a webhook URL. Start cancels the background context and aborts startup, propagating the cause (subscription or listener failure) with this prefix.

Source

Thrown at platform/max/max.go:177

		return fmt.Errorf("max: platform stopped")
	}
	p.handler = handler

	ctx, cancel := context.WithCancel(context.Background())
	p.ctx = ctx
	p.cancel = cancel

	// Verify token at startup
	if name, id, err := p.getMe(ctx); err != nil {
		slog.Warn("max: could not verify bot token", "error", err)
	} else {
		slog.Info("max: connected", "bot", name, "id", id)
	}

	if p.webhookURL != "" {
		if err := p.startWebhook(ctx); err != nil {
			cancel()
			return fmt.Errorf("max: start webhook: %w", err)
		}
		return nil
	}

	go p.pollLoop(ctx)
	return nil
}

func (p *Platform) Stop() error {
	p.mu.Lock()
	srv := p.webServer
	url := p.webhookURL
	p.stopping = true
	if p.cancel != nil {
		p.cancel()
	}
	p.mu.Unlock()
	if srv != nil {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Inspect the wrapped inner error: if it's a bind failure, free the port or change webhook_listen address.
2. If the inner error is "subscribe: ..." / "HTTP xxx", verify the webhook URL is publicly reachable and the token is valid.
3. Temporarily run in polling mode by removing the webhook_url option to isolate webhook-specific issues.

Example fix

// before
opts["webhook_url"] = "http://localhost:8080/hook" // not publicly reachable
// after
opts["webhook_url"] = "https://example.com/max/hook"

if url, ok := opts["webhook_url"].(string); ok && url != "" {
    u, err := neturl.Parse(url)
    if err != nil || u.Scheme != "https" { return errors.New("webhook_url must be a valid https URL") }
}

if err := p.Start(handler); err != nil {
    var inner error
    if errors.As(err, &inner) { slog.Error("max start failed", "err", err) }
    return fmt.Errorf("platform start failed: %w", err)
}

When it happens

Trigger: Configuring opts["webhook_url"] and calling Start when the local HTTP listener cannot bind, or the MAX webhook subscribe call fails (network error, bad URL, HTTP >= 300 from the API).

Common situations: Port already in use for the webhook server, unreachable/invalid public webhook URL passed to MAX, expired or missing bot token causing subscribe to be rejected.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• project %q preflight: %w
• project %q probe: %w
• project %q audit: %s
• run_as_user startup checks failed for %d project(s); see log
• platform %q not ready

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