{"record":{"id":"2f9976df78eeba20","repo":"chenhg5/cc-connect","slug":"matrix-homeserver-is-required","errorCode":null,"errorMessage":"matrix: homeserver is required","messagePattern":"matrix: homeserver is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"platform/matrix/matrix.go","lineNumber":68,"sourceCode":"\tgeneration           uint64\n\teverConnected        bool\n\tunavailableNotified  bool\n\tdedup                core.MessageDedup\n\thttpClient           *http.Client\n\tcryptoHelper         any //nolint:unused // *cryptohelper.CryptoHelper when built with goolm tag\n\tcrossSigningPassword string\n}\n\nconst (\n\tinitialBackoff = 2 * time.Second\n\tmaxBackoff     = 60 * time.Second\n\tstableWindow   = 10 * time.Second\n)\n\nfunc New(opts map[string]any) (core.Platform, error) {\n\thomeserver, _ := opts[\"homeserver\"].(string)\n\tif homeserver == \"\" {\n\t\treturn nil, fmt.Errorf(\"matrix: homeserver is required\")\n\t}\n\taccessToken, _ := opts[\"access_token\"].(string)\n\tif accessToken == \"\" {\n\t\treturn nil, fmt.Errorf(\"matrix: access_token is required\")\n\t}\n\tuserID, _ := opts[\"user_id\"].(string)\n\tallowFrom, _ := opts[\"allow_from\"].(string)\n\tcore.CheckAllowFrom(\"matrix\", allowFrom)\n\n\tgroupReplyAll, _ := opts[\"group_reply_all\"].(bool)\n\tshareSession, _ := opts[\"share_session_in_channel\"].(bool)\n\tautoJoin, _ := opts[\"auto_join\"].(bool)\n\tif !autoJoin {\n\t\t_, hasKey := opts[\"auto_join\"]\n\t\tif !hasKey {\n\t\t\tautoJoin = true // default true\n\t\t}\n\t}","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/platform/matrix/matrix.go#L50-L86","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nNew(map[string]any{\"access_token\": \"syt_...\", \"user_id\": \"@bot:example.org\"})\n// after\nNew(map[string]any{\"homeserver\": \"https://matrix.example.org\", \"access_token\": \"syt_...\", \"user_id\": \"@bot:example.org\"})","handlingStrategy":"validation","validationCode":"// Go: validate matrix options before calling New\nhs, _ := opts[\"homeserver\"].(string)\nif hs == \"\" {\n    return fmt.Errorf(\"config: matrix platform requires non-empty 'homeserver' (e.g. https://matrix.example.org)\")}\nif _, err := url.ParseRequestURI(hs); err != nil {\n    return fmt.Errorf(\"config: matrix 'homeserver' is not a valid URL: %w\", err)}","typeGuard":"func validHomeserver(opts map[string]any) (string, bool) {\n    hs, ok := opts[\"homeserver\"].(string)\n    return hs, ok && hs != \"\"\n}","tryCatchPattern":"plat, err := matrix.New(opts)\nif err != nil {\n    if err.Error() == \"matrix: homeserver is required\" {\n        return fmt.Errorf(\"config error: add homeserver = \\\"https://matrix.example.org\\\" to the [[platform]] block\")\n    }\n    return err\n}","preventionTips":["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."],"tags":["matrix","config","validation"],"backgroundTag":"missing-required-config-field","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}