cloudflare/cloudflared · error

Failed to format address: %v

Error message

Failed to format address: %v

What it means

sendReply serializes a SOCKS5 reply message with the target address; it supports IPv4, IPv6, and (via a preceding case) FQDN address types. If the net.Addr's IP cannot be encoded as 4 or 16 bytes (To4 and To16 both nil), the address type is unknown and the library returns this error instead of writing a malformed reply.

Source

Thrown at socks/request.go:127

		addrPort = 0

	case addr.FQDN != "":
		addrType = fqdnAddress
		addrBody = append([]byte{byte(len(addr.FQDN))}, addr.FQDN...)
		addrPort = uint16(addr.Port)

	case addr.IP.To4() != nil:
		addrType = ipv4Address
		addrBody = []byte(addr.IP.To4())
		addrPort = uint16(addr.Port)

	case addr.IP.To16() != nil:
		addrType = ipv6Address
		addrBody = []byte(addr.IP.To16())
		addrPort = uint16(addr.Port)

	default:
		return fmt.Errorf("Failed to format address: %v", addr)
	}

	// Format the message
	msg := make([]byte, 6+len(addrBody))
	msg[0] = socks5Version
	msg[1] = resp
	msg[2] = 0 // Reserved
	msg[3] = addrType
	copy(msg[4:], addrBody)
	msg[4+len(addrBody)] = byte(addrPort >> 8)
	msg[4+len(addrBody)+1] = byte(addrPort & 0xff)

	// Send the message
	_, err := w.Write(msg)
	return err
}

// readAddrSpec is used to read AddrSpec.

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Ensure the addr passed to sendReply/handleConnect has a populated net.IP (parse with net.ParseIP and assign req.DestAddr.IP)
2. For FQDN destinations without an IP, rely on the FQDN address type rather than passing an invalid IP
3. Validate constructed addresses with addr.IP != nil and net.ParseIP(addr.String()) before handling the request
4. If running a custom RequestHandler, check the reply send error and log the offending address

Example fix

// before
req.DestAddr.IP = nil // addr has no IP, reply fails to format

// after
if ip := net.ParseIP(host); ip != nil {
    req.DestAddr.IP = ip
}

if addr == nil || addr.IP == nil || (addr.IP.To4() == nil && addr.IP.To16() == nil) {
    return fmt.Errorf("cannot encode address %v as SOCKS5 reply", addr)
}

func isEncodableAddr(addr net.Addr) bool {
    ta, ok := addr.(*net.TCPAddr)
    return ok && ta.IP != nil && (ta.IP.To4() != nil || ta.IP.To16() != nil)
}

if err := handleRequest(conn); err != nil && strings.Contains(err.Error(), "Failed to format address") {
    log.Error().Err(err).Msg("constructed address lacks a valid IP")
}

When it happens

Trigger: sendReply being passed an addr whose IP field is neither a valid IPv4 nor IPv6 value — e.g. a zero-value &net.TCPAddr{}, an address with a nil/unparseable IP, or a non-IP net.Addr wrapped to fit.

Common situations: Custom dialer or access-policy code constructing a DestAddr/net.TCPAddr with an empty IP string; forwarding addresses produced by non-IP resolvers; a bug in user code that clears req.DestAddr.IP before the handler sends the bind/connect reply.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Failed to read auth methods: %v
• Failed to get command version: %v
• Unsupported command version: %v
• Unrecognized address type
• Failed to send reply: %v

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/b7f8171448cbaf0e. Report an issue: GitHub.