{"record":{"id":"5d64cbf3a53c2339","repo":"caddyserver/caddy","slug":"s-parsing-listen-address-s-v","errorCode":null,"errorMessage":"%s: parsing listen address '%s': %v","messagePattern":"(.+?): parsing listen address '(.+?)': (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/app.go","lineNumber":534,"sourceCode":"\t\t\t// this type of connection by checking if it's behind a TLS listener wrapper or if it implements tls.ConnectionState.\n\t\t\tsrv.server.Protocols.SetUnencryptedHTTP2(true)\n\t\t\t// when h2c is enabled but h2 disabled, we already removed h2 from NextProtos\n\t\t\t// the handshake will never succeed with h2\n\t\t\t// http2.ConfigureServer will enable the server to handle both h2 and h2c\n\t\t\th2server := new(http2.Server)\n\t\t\t//nolint:errcheck\n\t\t\thttp2.ConfigureServer(srv.server, h2server)\n\t\t}\n\n\t\t// this TLS config is used by the std lib to choose the actual TLS config for connections\n\t\t// by looking through the connection policies to find the first one that matches\n\t\ttlsCfg := srv.TLSConnPolicies.TLSConfig(app.ctx)\n\t\tsrv.configureServer(srv.server)\n\n\t\tfor lnIndex, lnAddr := range srv.Listen {\n\t\t\tlistenAddr, err := caddy.ParseNetworkAddress(lnAddr)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"%s: parsing listen address '%s': %v\", srvName, lnAddr, err)\n\t\t\t}\n\n\t\t\tsrv.addresses = append(srv.addresses, listenAddr)\n\n\t\t\tprotocols := srv.Protocols\n\t\t\tif srv.ListenProtocols != nil && srv.ListenProtocols[lnIndex] != nil {\n\t\t\t\tprotocols = srv.ListenProtocols[lnIndex]\n\t\t\t}\n\n\t\t\tprotocolsUnique := map[string]struct{}{}\n\t\t\tfor _, protocol := range protocols {\n\t\t\t\tprotocolsUnique[protocol] = struct{}{}\n\t\t\t}\n\t\t\t_, h1ok := protocolsUnique[\"h1\"]\n\t\t\t_, h2ok := protocolsUnique[\"h2\"]\n\t\t\t_, h2cok := protocolsUnique[\"h2c\"]\n\t\t\t_, h3ok := protocolsUnique[\"h3\"]\n","sourceCodeStart":516,"sourceCodeEnd":552,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/app.go#L516-L552","documentation":"During Start (after provisioning and placeholder replacement), each listen address is parsed again with caddy.ParseNetworkAddress. If a placeholder-expanded address no longer parses (e.g. an env var supplied a value like \"http://x\" or omitted the port), Start fails with this error naming server and address.","triggerScenarios":"A listen placeholder resolving to a malformed value at runtime: {env.PORT}=\"8080\" alone with no host separator is fine, but {env.ADDR}=\"https://0.0.0.0\" or an empty value yields an unparseable address.","commonSituations":"Config passes validation with literal addresses but Start uses expanded ones; env vars changed between validate and run; container env injecting URLs instead of host:port.","solutions":["Print the expanded value inside the same environment (caddy adapt --pretty, or log the env) and correct it to network/host:port form","Use Caddyfile-style env defaults {$VAR:...} so a missing var cannot produce an empty address","Run `caddy validate` with the same env as the real service"],"exampleFix":"// before\n\"listen\": [\"{env.BIND}\"] with BIND=\"https://0.0.0.0\"\n// after\n\"listen\": [\"{env.BIND}:443\"] with BIND=\"0.0.0.0\"","handlingStrategy":"validation","validationCode":"// validate AFTER placeholder expansion, in the runtime environment\nfor _, a := range srvCfg.Listen {\n    expanded, err := repl.ReplaceOrErr(a, true, true)\n    if err != nil { return err }\n    if _, err := caddy.ParseNetworkAddress(expanded); err != nil {\n        return fmt.Errorf(\"expanded listen %q invalid: %w\", expanded, err)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `caddy validate` with the exact environment (env_file/unit) used at runtime","Use {$VAR:default} defaults so expansion can never yield an empty or scheme-prefixed string","Log resolved listen addresses at startup before Caddy starts"],"tags":["caddy","listener","placeholders","startup","environment"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}