{"record":{"id":"e2b7d832d04860b0","repo":"caddyserver/caddy","slug":"the-scheme-wss-is-only-supported-in-browsers-u","errorCode":null,"errorMessage":"the scheme wss:// is only supported in browsers; use https:// instead","messagePattern":"the scheme wss:// is only supported in browsers; use https:// instead","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"caddyconfig/httpcaddyfile/addresses.go","lineNumber":275,"sourceCode":"\n\t\t\tsbaddrs = append(sbaddrs, sbAddrAssociation{\n\t\t\t\taddressesWithProtocols: addressesWithProtocols,\n\t\t\t\tserverBlocks:           serverBlocks,\n\t\t\t})\n\t\t}\n\t}\n\n\treturn sbaddrs\n}\n\n// listenersForServerBlockAddress essentially converts the Caddyfile site addresses to a map from\n// Caddy listener addresses and the protocols to serve them with to the parsed address for each server block.\nfunc (st *ServerType) listenersForServerBlockAddress(sblock serverBlock, addr Address,\n\toptions map[string]any,\n) (map[string]map[string]struct{}, error) {\n\tswitch addr.Scheme {\n\tcase \"wss\":\n\t\treturn nil, fmt.Errorf(\"the scheme wss:// is only supported in browsers; use https:// instead\")\n\tcase \"ws\":\n\t\treturn nil, fmt.Errorf(\"the scheme ws:// is only supported in browsers; use http:// instead\")\n\tcase \"https\", \"http\", \"\":\n\t\t// Do nothing or handle the valid schemes\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"unsupported URL scheme %s://\", addr.Scheme)\n\t}\n\n\t// figure out the HTTP and HTTPS ports; either\n\t// use defaults, or override with user config\n\thttpPort, httpsPort := strconv.Itoa(caddyhttp.DefaultHTTPPort), strconv.Itoa(caddyhttp.DefaultHTTPSPort)\n\tif hport, ok := options[\"http_port\"]; ok {\n\t\thttpPort = strconv.Itoa(hport.(int))\n\t}\n\tif hsport, ok := options[\"https_port\"]; ok {\n\t\thttpsPort = strconv.Itoa(hsport.(int))\n\t}\n","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/caddyconfig/httpcaddyfile/addresses.go#L257-L293","documentation":"A site address key used the wss:// scheme. Caddy rejects it because wss:// is a browser-only API concept (WebSocket-over-TLS); the server should be described as https:// and it will serve WebSockets over TLS automatically.","triggerScenarios":"A Caddyfile site block key starts with wss://, e.g. 'wss://example.com { }'. listenersForServerBlockAddress rejects the scheme before any listener is built.","commonSituations":"Copy-pasting a client-side WebSocket URL from JavaScript (new WebSocket('wss://...')) into a Caddyfile as the site address.","solutions":["Change wss:// to https:// in the site label; WebSocket upgrade handling is automatic","Keep clients using wss:// to connect — only the Caddyfile label changes"],"exampleFix":"# before\nwss://example.com {\n}\n# after\nhttps://example.com {\n}","handlingStrategy":"validation","validationCode":"if strings.HasPrefix(siteKey, \"wss://\") {\n    return errors.New(\"use https:// for site addresses; clients keep wss://\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat wss:// as client-only vocabulary","Template site labels from https://, not from frontend WebSocket URLs"],"tags":["caddyfile","websocket","site-address","scheme"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}