Common Error Messages¶
This page lists the errors AddressTools reports most often, what each one means, and how to resolve it.
Errors reach you in two ways. Interactive errors appear inside the AddressTools component. Errors raised by batch and automated verification are emailed to the address set in Batch Verification Alert Email Address.
US ZIP Code Errors¶
These apply to United States addresses and depend on the US ZIP code reference data being installed. See Install Country Data.
| Message | Cause | Resolution |
|---|---|---|
'Billing Zip/Postal Code' contains an invalid ZIP/Postal code |
Allow Only Listed ZIP Codes is on and the ZIP code is not installed. | Enter a ZIP code held in your installed US ZIP code data or add a new record |
'Billing Zip/Postal Code' is marked as 'Decommissioned', please replace with the current, valid ZIP code |
The ZIP code is no longer in use. | Replace it with the current ZIP code for the address. |
'Billing Zip/Postal Code' is marked as 'Not Acceptable', please replace with the current, valid ZIP code |
The ZIP code is not valid for postal use. | Replace it with a ZIP code that accepts mail. |
Invalid state for postal code 90210. Valid state: California. |
The state does not match the ZIP code. The message lists the valid state. | Correct the state, or the ZIP code, so the two agree. |
Invalid city for postal code 90210. Valid cities: Beverly Hills. |
The city does not match the ZIP code. The message lists the valid cities. | Correct the city to one of those listed, or the ZIP code. |
Component and Address Search Errors¶
| Message | Cause | Resolution |
|---|---|---|
Unable to load address configuration. Please refresh the page or contact your administrator. |
The component could not load the address block settings. | Refresh the page. If it persists, ask your administrator to check the address block. |
Unable to load address search. Please try again later. |
The address search could not be prepared. | Try again. If it persists, contact your administrator. |
Service authentication failed; please refresh your authentication token on the AddressTools Administration page. |
The verification service rejected the org's credentials. | Ask your administrator to refresh the token. See Create an Authentication Token. |
Error saving address |
The save failed and Salesforce returned no specific reason. A validation rule, required field or field-level security on the object is the usual cause. | Check the object's validation rules and your access to the address fields. |
Error loading data |
The component could not read the record's address. | Refresh the page, and check that you have access to the mapped address fields. |
No addresses matched the search text. |
The search ran and found nothing for the text supplied. In an Agentforce agent this can also mean the action received a placeholder value rather than the address the user gave. | Check the search text. In an agent, open the Trace tab, select the Action: Search Address row and read the action input, which shows what was actually sent. |
License and Permission Errors¶
| Message | Cause | Resolution |
|---|---|---|
User doesn't have a valid AddressTools license. |
The user saving the record has no AddressTools license assigned. | Assign a license. See Assign User Licenses. |
The current user does not have query access to the CountryObject__c object or one of its fields to which access is required. |
The user lacks access to an object or field AddressTools requires. The object name and access type vary. | Check the Permission Set assignment. See Granting User Permissions. |
Note
Integration users need a license as well, because the trigger runs as the user whose action saved the record.
Errors From Batch and Automated Verification¶
Batch and record-triggered verification run in the background, so their failures are not shown to the user saving the record. Errors are emailed to the address in Batch Verification Alert Email Address, and batch runs record an error count in Job History.
| Message | Cause | Resolution |
|---|---|---|
This record cannot be verified, a country value is missing. You have not been charged for this request. |
The address has no country value. | Add a country to the address, then verify it again. The address status stays Not checked until it is verified. |
If the alert emails do not arrive, check Setup > Email > Deliverability and confirm Access to Send Email is set to All email.
See Configure Batch Address Verification and Configure Automated Verification via a Record-Triggered Flow.
Salesforce Errors That Affect AddressTools¶
Some failures originate in Salesforce configuration rather than in AddressTools.
-
A restricted address status picklist rejects the value returned by verification. Clear Restrict picklist to the values defined in the value set on the field. See Create an Address Status Field.
-
A Salesforce validation rule, required field or duplicate rule on the object can block a save that AddressTools has already processed.
-
Field-level security can hide a mapped address field from a user, which prevents AddressTools from reading or writing it.
Missing State Values With State and Country/Territory Picklists¶
Where your org uses the Salesforce State and Country/Territory Picklists, the state and country fields accept only the values held in those picklists.
A verified address can return a state that is not one of them, for example a county code returned for a United Kingdom address. Rather than failing the save, AddressTools leaves the state empty, so the rest of the verified address is still written to the record. Enter the state manually if your org requires one.
Trace IDs¶
Every request AddressTools makes to the ProvenWorks service carries a trace ID, a 32-character code of lower-case letters and digits. When a request fails, the error reported in your org includes that ID. A single ID covers every request in the same operation: one search session, one batch run or one data installation run.
A trace ID appears wherever AddressTools reports a failed request:
- Interactive address search: when a search or address retrieval fails in the AddressTools search box on a record, in PowerSearch or in the search modal, a Trace ID line appears beneath the error message.
- Batch address verification: the Trace ID column of Job History on the Batch Address Verification page, and the failure email sent to the Batch Verification Alert Email Address. See Configure Batch Address Verification.
- Automated verification via a record-triggered flow: the error message for each failed record ends with the code, both in the alert email and in the Automated Address Verification Error platform event.
- Reference data installation: each failed stage on the Installation tab shows its message with the code beneath it, and the Installation Completed with Errors dialog lists them. See Install Country Data.
- Create Token or Update Token on the Installation tab: a failed token request shows its message with the code beneath the step.
- Licensing & Lookups tab: if your remaining verification lookups cannot be loaded, an error notification with the code appears in place of the lookup table. Click Refresh to retry.
- Search Address and Select Address actions in a flow or an Agentforce agent: when Success is false, the Message output ends with the code. See Search and Select Address Verification Actions.
If you contact support@provenworks.com about a failure, include the trace ID. It is the most helpful detail you can send, as it lets ProvenWorks go straight to the requests that failed. One ID covers a whole run or search session, so a single ID is enough even when several records failed. Use the copy button beside an ID where one is shown, or select the text and copy it.