What causes "matrix: homeserver is required" in chenhg5/cc-connect?

Add homeserver = "https://matrix.example.org" to the matrix platform section of config.toml.

matrix: homeserver is required

Error message

matrix: homeserver is required

What it means

A constructor validation error: the Matrix platform's New() requires a non-empty 'homeserver' option. Without a homeserver URL the mautrix.Client cannot be built, so the adapter refuses construction with this explicit error rather than failing later with a confusing nil-client panic.

Source

Thrown at platform/matrix/matrix.go:68

	generation           uint64
	everConnected        bool
	unavailableNotified  bool
	dedup                core.MessageDedup
	httpClient           *http.Client
	cryptoHelper         any //nolint:unused // *cryptohelper.CryptoHelper when built with goolm tag
	crossSigningPassword string
}

const (
	initialBackoff = 2 * time.Second
	maxBackoff     = 60 * time.Second
	stableWindow   = 10 * time.Second
)

func New(opts map[string]any) (core.Platform, error) {
	homeserver, _ := opts["homeserver"].(string)
	if homeserver == "" {
		return nil, fmt.Errorf("matrix: homeserver is required")
	}
	accessToken, _ := opts["access_token"].(string)
	if accessToken == "" {
		return nil, fmt.Errorf("matrix: access_token is required")
	}
	userID, _ := opts["user_id"].(string)
	allowFrom, _ := opts["allow_from"].(string)
	core.CheckAllowFrom("matrix", allowFrom)

	groupReplyAll, _ := opts["group_reply_all"].(bool)
	shareSession, _ := opts["share_session_in_channel"].(bool)
	autoJoin, _ := opts["auto_join"].(bool)
	if !autoJoin {
		_, hasKey := opts["auto_join"]
		if !hasKey {
			autoJoin = true // default true
		}
	}

View on GitHub (pinned to 4000b2338a)

Solutions

Add homeserver = "https://matrix.example.org" to the matrix platform section of config.toml.
Check the key spelling — it must be exactly 'homeserver'.
Ensure the value is a TOML string, not a number or bare URL with wrong quoting.
If using env expansion, verify the variable is set at process start so the resolved value is non-empty.
Run the New() call with a quick pre-check or consult the tests (TestNew_MissingHomeserver) showing the expected config shape.

Example fix

// before
New(map[string]any{"access_token": "syt_...", "user_id": "@bot:example.org"})
// after
New(map[string]any{"homeserver": "https://matrix.example.org", "access_token": "syt_...", "user_id": "@bot:example.org"})

Defensive patterns

Strategy: validation

Validate before calling

// Go: validate matrix options before calling New
hs, _ := opts["homeserver"].(string)
if hs == "" {
    return fmt.Errorf("config: matrix platform requires non-empty 'homeserver' (e.g. https://matrix.example.org)")}
if _, err := url.ParseRequestURI(hs); err != nil {
    return fmt.Errorf("config: matrix 'homeserver' is not a valid URL: %w", err)}

Type guard

func validHomeserver(opts map[string]any) (string, bool) {
    hs, ok := opts["homeserver"].(string)
    return hs, ok && hs != ""
}

Try / catch

plat, err := matrix.New(opts)
if err != nil {
    if err.Error() == "matrix: homeserver is required" {
        return fmt.Errorf("config error: add homeserver = \"https://matrix.example.org\" to the [[platform]] block")
    }
    return err
}

Prevention

Validate config.toml against config.example.toml at startup; fail fast on missing keys.
Always quote the homeserver as a TOML string with the https:// scheme.
Use consistent key names ('homeserver', 'access_token', 'user_id') across deployments.
Lint configs in CI with a schema check that requires 'homeserver' for the matrix platform.
Beware non-string TOML values: the type assertion silently yields "" and triggers this error.

When it happens

Trigger: New(opts map[string]any) is called with opts lacking the 'homeserver' key or containing opts["homeserver"] = "" — e.g. config.toml platform section missing the homeserver field, a type mismatch so the string assertion fails (homeserver, _ := opts["homeserver"].(string) yields ""), or an empty environment-variable expansion.

Common situations: User forgot the homeserver line in the [[platform]] TOML block; homeserver value typed under the wrong key name (e.g. 'server' or 'url'); value supplied as a non-string (e.g. TOML integer) so the type assertion silently produces ""; template/env placeholder resolved to empty string.

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/2f9976df78eeba20. Report an issue: GitHub.