{"record":{"id":"0508a7fbb9afea12","repo":"caddyserver/caddy","slug":"for-now-urls-for-proxy-upstreams-only-support-sch","errorCode":null,"errorMessage":"for now, URLs for proxy upstreams only support scheme, host, and port components","messagePattern":"for now, URLs for proxy upstreams only support scheme, host, and port components","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/reverseproxy/addresses.go","lineNumber":107,"sourceCode":"\t\t\t\t}\n\t\t\t\ttoURL, err = url.Parse(strings.ReplaceAll(upstreamAddr, portRange, \"0\"))\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn parsedAddr{}, fmt.Errorf(\"parsing upstream URL: %v\", err)\n\t\t\t\t}\n\t\t\t\tport = portRange\n\t\t\t} else {\n\t\t\t\treturn parsedAddr{}, fmt.Errorf(\"parsing upstream URL: %v\", err)\n\t\t\t}\n\t\t}\n\t\tif port == \"\" {\n\t\t\tport = toURL.Port()\n\t\t}\n\n\t\t// there is currently no way to perform a URL rewrite between choosing\n\t\t// a backend and proxying to it, so we cannot allow extra components\n\t\t// in backend URLs\n\t\tif toURL.Path != \"\" || toURL.RawQuery != \"\" || toURL.Fragment != \"\" {\n\t\t\treturn parsedAddr{}, fmt.Errorf(\"for now, URLs for proxy upstreams only support scheme, host, and port components\")\n\t\t}\n\n\t\t// ensure the port and scheme aren't in conflict\n\t\tif toURL.Scheme == \"http\" && port == \"443\" {\n\t\t\treturn parsedAddr{}, fmt.Errorf(\"upstream address has conflicting scheme (http://) and port (:443, the HTTPS port)\")\n\t\t}\n\t\tif toURL.Scheme == \"https\" && port == \"80\" {\n\t\t\treturn parsedAddr{}, fmt.Errorf(\"upstream address has conflicting scheme (https://) and port (:80, the HTTP port)\")\n\t\t}\n\t\tif toURL.Scheme == \"h2c\" && port == \"443\" {\n\t\t\treturn parsedAddr{}, fmt.Errorf(\"upstream address has conflicting scheme (h2c://) and port (:443, the HTTPS port)\")\n\t\t}\n\n\t\t// if port is missing, attempt to infer from scheme\n\t\tif port == \"\" {\n\t\t\tswitch toURL.Scheme {\n\t\t\tcase \"\", \"http\", \"h2c\":\n\t\t\t\tport = \"80\"","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/reverseproxy/addresses.go#L89-L125","documentation":"The upstream address parsed successfully but contains URL components Caddy cannot honor: a path, query string, or fragment (e.g. 'http://host/base?x=1#f'). Because there is no rewrite step between upstream selection and dialing, Caddy only accepts scheme, host, and port in upstream addresses.","triggerScenarios":"Configuring 'reverse_proxy http://backend/api/v1' or 'http://backend?token=abc'; also 'caddy reverse-proxy --to http://host/path'.","commonSituations":"Assuming reverse_proxy path-appends like a redirect target; pasting full API URLs from documentation instead of bare host:port.","solutions":["Strip path/query/fragment from the upstream: 'reverse_proxy http://backend'.","If you need to change the request path for the backend, use 'rewrite * /api/v1{uri}' before reverse_proxy.","To forward a query-based token, set it with 'header_up' instead of embedding it in the upstream URL."],"exampleFix":"# before\nreverse_proxy http://backend/api/v1\n\n# after\nhandle {\n  rewrite * /api/v1{uri}\n  reverse_proxy http://backend\n}","handlingStrategy":"validation","validationCode":"if u, err := url.Parse(upstream); err == nil {\n    if u.Path != \"\" || u.RawQuery != \"\" || u.Fragment != \"\" {\n        return fmt.Errorf(\"upstream %q must not contain path/query/fragment\", upstream)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never paste full API URLs as upstreams; upstreams are dial addresses, not request targets.","Do path manipulation with rewrite/matchers, not the upstream address.","Add header values via header_up instead of query strings in the address."],"tags":["reverse-proxy","upstream","rewrite","configuration"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}