owasp-amass/amass · error

failed to parse address

Error message

failed to parse address

What it means

The C call libpostal_parse_address returned a NULL response pointer, meaning libpostal itself failed to parse the (valid UTF-8) address string with the given parser options. This is a generic nil-result guard around the C API; common causes are empty/whitespace input or missing libpostal language data for the requested options.

Source

Thrown at internal/libpostal/cgo_specific.go:80

	cOptions := C.libpostal_get_address_parser_default_options()
	if options.Language != "" {
		cLanguage := C.CString(options.Language)
		defer C.free(unsafe.Pointer(cLanguage))

		cOptions.language = cLanguage
	}

	if options.Country != "" {
		cCountry := C.CString(options.Country)
		defer C.free(unsafe.Pointer(cCountry))

		cOptions.country = cCountry
	}

	cAddressParserResponsePtr := C.libpostal_parse_address(cAddress, cOptions)
	if cAddressParserResponsePtr == nil {
		return nil, errors.New("failed to parse address")
	}
	cAddressParserResponse := *cAddressParserResponsePtr

	cNumComponents := cAddressParserResponse.num_components
	cComponents := cAddressParserResponse.components
	cLabels := cAddressParserResponse.labels
	numComponents := uint64(cNumComponents)
	parsedComponents := make([]ParsedComponent, numComponents)

	// Accessing a C array
	cComponentsPtr := (*[1 << 30](*C.char))(unsafe.Pointer(cComponents))[:numComponents:numComponents]
	cLabelsPtr := (*[1 << 30](*C.char))(unsafe.Pointer(cLabels))[:numComponents:numComponents]

	var i uint64
	for i = range numComponents {
		parsedComponents[i] = ParsedComponent{
			Label: C.GoString(cLabelsPtr[i]),
			Value: C.GoString(cComponentsPtr[i]),

View on GitHub (pinned to 79299dce87)

Solutions

1. Trim whitespace and reject empty address strings before invoking the parser
2. Check that libpostal's data files cover the requested language/country options
3. Fall back to returning the raw address as a single component when parsing is not critical to the caller

When it happens

Trigger: Thrown at internal/libpostal/cgo_specific.go:80 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

AI-assisted analysis of owasp-amass/amass@79299dce87 (2026-09-06). Data as JSON: /api/errors/86c98a15e752863b. Report an issue: GitHub.