{"record":{"id":"8af75e838ed798d7","repo":"ipfs/kubo","slug":"unsupported-api-address-s","errorCode":null,"errorMessage":"unsupported API address: %s","messagePattern":"unsupported API address: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/start.go","lineNumber":351,"sourceCode":"\tvar tpt http.RoundTripper\n\tswitch network {\n\tcase \"tcp\", \"tcp4\", \"tcp6\":\n\t\ttpt = http.DefaultTransport\n\t\t// RPC over HTTPS requires explicit schema in the address passed to cmdhttp.NewClient\n\t\thttpAddr := apiAddr.String()\n\t\tif !strings.HasPrefix(host, \"http:\") && !strings.HasPrefix(host, \"https:\") && (strings.Contains(httpAddr, \"/https\") || strings.Contains(httpAddr, \"/tls/http\")) {\n\t\t\thost = \"https://\" + host\n\t\t}\n\tcase \"unix\":\n\t\tpath := host\n\t\thost = \"unix\"\n\t\ttpt = &http.Transport{\n\t\t\tDialContext: func(_ context.Context, _, _ string) (net.Conn, error) {\n\t\t\t\treturn net.Dial(\"unix\", path)\n\t\t\t},\n\t\t}\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"unsupported API address: %s\", apiAddr)\n\t}\n\n\tapiAuth, specified := req.Options[corecmds.ApiAuthOption].(string)\n\tif specified {\n\t\tauthorization := config.ConvertAuthSecret(apiAuth)\n\t\ttpt = auth.NewAuthorizedRoundTripper(authorization, tpt)\n\t}\n\n\thttpClient := &http.Client{\n\t\tTransport: otelhttp.NewTransport(tpt),\n\t}\n\topts = append(opts, cmdhttp.ClientWithHTTPClient(httpClient))\n\n\t// Fetch remove version, as some feature compatibility might change depending on it.\n\tremoteVersion, err := getRemoteVersion(tracingWrappedExecutor{cmdhttp.NewClient(host, opts...)})\n\tif err != nil {\n\t\treturn nil, err\n\t}","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/start.go#L333-L369","documentation":"After resolving the API multiaddr, makeExecutor inspects its network type via manet.DialArgs and only supports tcp/tcp4/tcp6 and unix transports for the HTTP RPC client. Any other multiaddr protocol (e.g. ipfs/p2p, ws, quic) reaches the default branch and fails with 'unsupported API address: <multiaddr>'.","triggerScenarios":"Setting `--api` (or Addresses.API / the api file) to a multiaddr whose transport is not tcp or unix, e.g. `--api /dns4/example.com/tcp/5001/ws`, `/ip4/1.2.3.4/udp/5001/quic-v1`, or a `/p2p-circuit/...` address.","commonSituations":"Copying a swarm listening address (quic/websocket) from `ipfs id` into --api instead of the RPC address from Addresses.API; trying to point the CLI at a gateway address over ws; hand-editing the api file with a websocket multiaddr.","solutions":["Use a plain TCP multiaddr for --api, e.g. `--api /ip4/127.0.0.1/tcp/5001` or `/dns4/host/tcp/5001` (add /https or /tls/http if TLS is used).","For unix sockets use `--api /unix/path/to/socket`.","Check the daemon's actual API address with `ipfs config Addresses.API` on the daemon host and use that value."],"exampleFix":"# before\nipfs --api /ip4/127.0.0.1/udp/5001/quic-v1 id\n# after\nipfs --api /ip4/127.0.0.1/tcp/5001 id","handlingStrategy":"validation","validationCode":"addr, err := ma.NewMultiaddr(apiStr)\nif err == nil {\n    switch _, _, err := manet.DialArgs(addr); {\n    case err != nil:\n        return fmt.Errorf(\"bad api addr: %w\", err)\n    default:\n        // ok: tcp or unix transports only\n    }\n}","typeGuard":"func isSupportedAPIAddr(addr ma.Multiaddr) bool {\n    network, _, err := manet.DialArgs(addr)\n    return err == nil && (strings.HasPrefix(network, \"tcp\") || network == \"unix\")\n}","tryCatchPattern":null,"preventionTips":["Only pass RPC addresses (Addresses.API) to --api, never swarm or gateway addresses.","Avoid copying quic/ws multiaddrs from `ipfs id` into --api.","For remote RPC over TLS use /https or /tls/http on a tcp multiaddr, not /ws.","Validate multiaddrs with ma.NewMultiaddr before storing them in the api file."],"tags":["cli","kubo","multiaddr","api-address"],"backgroundTag":"unsupported-api-address-scheme","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}