Troubleshooting the plugin

Most of the time, the plugin works fine out of the box. However, we've assembled this page over years of experience for those who are having difficulties.

On this page

START HERE: Debugging tips

If you're having trouble getting the plugin to work or display correctly on your site, our first recommendation always is to remove all other Javascript and CSS from your page. Then see if the plugin works. You can use a tool like jsFiddle to test it out in isolation.

If the plugin works by itself, then there was conflicting Javascript or CSS on the page before. Slowly add the other Javascript and CSS back into your page piece by piece, checking the plugin's functionality each time. Once the plugin stops working, you know which piece of code is interfering.

Also monitor the Javascript console to check for any errors and use the browser's element inspector tools to see how CSS rules are being applied.

You may also find it helpful to enable debug mode to peer inside the mind of the plugin.

What is "debug mode" and how do I enable it?

Debug mode allows you to better see what's happening under the hood while you're developing, testing, or debugging the plugin on your site. To enable it, set debug: true during initialization. (Never do this in production.) Mapped address fields will take on a yellow color and be labeled by the type of field they were mapped as. The Javascript console in your browser will fill up with logging events as fields are mapped, values are changed, and verifications take place. Open your browser's dev tools to see the console and follow along.

Verification isn't happening at all, or it isn't updating some of the fields.

Check to make sure your mapping is correct. Help the plugin by properly telling it which input fields to attach to.

My state (or other) field is a drop-down (<select>) element.

Great! Just make sure that the "text" attributes (what is displayed to the user in the <option> tags) is either the full name of a state or the two-letter abbreviation. The "value" attributes of the <option> tags can be anything you want. They can even be blank! If you do not enter a default value in the first <option> tag then we will insert one for you. This enables autocomplete to work properly.

To function properly, those "text" attributes must match the full name of the state or the official, two-letter state abbreviations. Example: "California," "Iowa," "Maryland," etc. or "CA," "IA," "MD," etc. These can be all uppercase, all lowercase, or any combination of cases.

Note: State dropdowns only play well for US addresses. Using a state dropdown for other countries may or may not work properly. We receommend using a text field instead.

Verification happens, but it takes a few seconds and doesn't change anything.

This is most likely because your website key is wrong or doesn't match the host/domain name exactly as shown by the URL in the browser. You must be viewing the page in a web browser using a host name like "localhost," an IP address, or a domain name. Going to "File" then "Open" in your browser will not work. Also, authorizing a website key for mysite.com does not make it work on www.mysite.com or any other subdomains of mysite.com. For that you would need to use the wildcard character like *. Thus, *.mysite.com would work for any subdomain of mysite.com

You can be sure there is a website key mismatch by opening your browser's dev tools and clicking on the "Network" tab and "Console" tab to monitor requests and errors. An error code of 401 means that your key and/or hostname is bad.

Ensure that the key you're using is allowed on the IP address, domain name, or other host name exactly as it is shown in the browser.

An address suggested in autocomplete didn't validate!

There are many reasons for this. In order to stay fast, address suggestions as you type are not guaranteed to be valid, nor do they come with ZIP Codes. Addresses must still go through the verification process. Autocomplete does not use any lookups against your account; lookups are only deducted from your balance when when the address is submitted for verification. Autocomplete suggestions are also not guaranteed to be in standardized format or cased properly.

Autocomplete said "No suggestions" to an address that validated.

Being a free service, the autocomplete service contains most—but not all—entries in its index. For example, only USPS-preferred city names are in the index, not nicknames like "St. Louis" where it should be "Saint Louis." Addresses, especially brand new addresses, can still be validated even if autocomplete has no suggestions for it. Further, LiveAddress can fix misspellings in user input and still validate the address on some occasions, whereas autocomplete will only suggest addresses matching what the user has typed.

Suggestions aren't filtered until I start typing a street name.

Street names are required for filtering to occur. This is necessary to keep the autocomplete service fast. You can hide autocomplete results until a street name is entered by setting waitForStreet to true when configuring the plugin.

Autocomplete always says "No suggestions" when using a filter.

Make sure city names are spelled exactly correctly and have no punctuation. Make sure you're using the USPS-preferred city names. If you're filtering by state, make sure you're using the official two-letter state abbreviations only. Make sure there are no periods in the state abbreviations.

How can I programmatically click the "Verify" button?

Use the .verify(addressID) function by passing in the addressID of the form you want to manually verify.

How do I get the addressID?

Use .getMappedAddresses()[index].id() where index is the index of the address you are trying to access. Also, the addressID is returned with the Address object when .makeAddress(addressData) is called.

Hey, it doesn't work in Internet Explorer {VERSION NUMBER HERE}!

Here is a list of modern browsers. Currently IE 11 is the oldest version supported by Microsoft.


Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff