owasp-amass/amass · warning

libpostal is not available

Error message

libpostal is not available

What it means

Thrown by postalServerParseAddress when isPostalServerAvailable() reports that the local libpostal REST server is not reachable. Address parsing is delegated to an external libpostal service; without it, StreetAddressToLocation cannot produce Location assets. This is an optional external-dependency availability error.

Source

Thrown at engine/plugins/support/location.go:119

			}
		}
	}

	// attempt to convert the province to its two-letter abbreviation
	if loc.Country != "" && len(loc.Province) > 2 {
		if c := pioz.Get(loc.Country); c != nil {
			if sub := c.SubdivisionByName(loc.Province); sub.Type != "" {
				loc.Province = sub.Code
			}
		}
	}

	return loc
}

func postalServerParseAddress(address string) ([]parsedComponent, error) {
	if !isPostalServerAvailable() {
		return nil, errors.New("libpostal is not available")
	}

	reqJSON, err := json.Marshal(parseRequest{Address: address})
	if err != nil {
		return nil, err
	}

	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()

	resp, err := amasshttp.RequestWebPage(ctx, amasshttp.DefaultClient, &amasshttp.Request{
		Method: "POST",
		URL:    "http://" + postalHost + ":" + postalPort + "/parse",
		Body:   string(reqJSON),
	})
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 79299dce87)

Solutions

1. Start the libpostal REST server (e.g. docker run -p 8080:8080 openresty/libpostal-rest or equivalent) before the scan
2. Verify the configured postal server address/port matches the running service
3. Add a startup health check that waits for the postal server before address parsing
4. Skip address-to-location enrichment gracefully when libpostal is unavailable

Example fix

// before
loc, err := support.StreetAddressToLocation(session, addr)
if err != nil {
	return err
}
// after
loc, err := support.StreetAddressToLocation(session, addr)
if err != nil {
	// libpostal unavailable; continue without location enrichment
	return nil
}

resp, err := http.Get(fmt.Sprintf("http://%s:%d/", postalHost, postalPort))
if err != nil {
	// libpostal unavailable; skip address parsing
}

null

loc, err := support.StreetAddressToLocation(session, addr)
if err != nil {
	if strings.Contains(err.Error(), "libpostal is not available") {
		// fall back: keep the raw address without location enrichment
		return nil
	}
	return err
}

When it happens

Trigger: StreetAddressToLocation is called with an address, and the libpostal parse server is not running or not listening on the expected port, so isPostalServerAvailable() returns false before any HTTP request is made.

Common situations: libpostal service not installed or not started (e.g. docker container for nlpodyssey/libpostal not running); wrong REST address/port configuration; server crashed or still starting when the scan ran.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• failed to cast the DomainRecord
• failed to cast the IPNetRecord
• failed to cast the TLSCertificate asset
• failed to obtain the subject contact record
• failed to obtain the subject organizations

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