Troubleshooting
Fixes for the most common Waybill problems.
I just installed Waybill and can't find its fields
Jira creates the fields a few minutes after the app is installed. Look under Settings → Work items → Fields for Tracking Number and the Shipping fields, wait a few minutes and refresh if they are not there yet, then add them to your screens (see the setup guide).
Nothing happens after I enter a tracking number
- Check that a Jira administrator has saved credentials for the carrier (Apps → Waybill → Carrier credentials tab). Without them the work item shows Carrier Not Configured.
- Confirm the shipping fields are on the project's screens (Settings → Work items → Screens).
- Confirm the space has not been switched off (Space settings → Waybill → "Don't refresh shipments in this space").
- Wait a few seconds and reload the work item. Updates run in the background.
- Open the Waybill panel on the work item. If the carrier had a problem, the panel shows a warning with the carrier's error message.
Shipping Status says "Unrecognized Number"
The number does not match a UPS, FedEx, USPS or DHL format. Check for typos or missing digits. Extra spaces, dashes and other punctuation are removed automatically, and a tracking number inside a longer sentence is found automatically. Text that does not look like a tracking number is left exactly as you typed it. Numbers from other carriers are not supported.
Shipping Status says "Lookup Pending"
The carrier had a temporary problem when the tracking number was entered, for example it was busy, rate limiting requests, or could not be reached. Nothing is wrong with your setup. Waybill retries automatically at the next hourly run, and you can also click Refresh now in the Waybill panel. If it stays pending for many hours, check the carrier's status page and that your carrier credentials and quota are fine (the DHL free plan is small).
Shipping Status says "Error"
The app could not get information for the tracking number you just entered. The reason is in Shipping Status Detail and in the Waybill panel, for example "USPS rejected the credentials (HTTP 401)". Fix the cause (usually the carrier credentials, see "The credentials are rejected"), then click Refresh now in the Waybill panel. Any information from a previously entered tracking number is cleared when this happens.
Shipping Status says "Not Found"
The carrier does not have this shipment yet. New labels can take several hours to appear. The app checks again on the next scheduled refresh.
Shipping Status says "Carrier Not Configured"
A Jira administrator needs to add credentials for the named carrier. See the "Get API credentials" guide.
The credentials are rejected when I save them
- Make sure you copied the production credentials, not sandbox or test ones.
- Make sure the Tracking API is added to your carrier application.
- Check for extra spaces at the start or end of the values.
- New developer applications can take a few minutes (DHL: longer, pending approval) to become active.
Scheduled updates are not running
- Check the settings under Apps → Waybill. At least one status must be selected; with none selected, nothing is refreshed on the schedule.
- Check the work item matches the site rules (or its space's own rules): status, work type and JQL filter.
- Shipments that are Delivered or Returned are no longer refreshed.
- The refresh interval is a maximum wait, not an exact schedule. The background job runs once an hour, so with a 4 hour interval a work item is re-checked at the hourly run just before it would pass 4 hours (about every 3 to 4 hours), and with 1 hour it is checked at every run. A work item is never left longer than the interval.
- Check Shipping Last Checked on the work item to see when it last succeeded.
Some fields are empty
- Estimated Delivery is only filled while a shipment is on its way, and only if the carrier provides one.
- Delivered At is only filled after delivery.
- Fields that the carrier does not report stay empty.
Times look wrong
Times are shown in your own Jira time zone, with the time zone abbreviation. Carrier scan times are converted from the carrier's data; when a carrier sends a time without a time zone, the app treats it as UTC, which can be off by a few hours.
I can't see the Space settings page
Only space administrators and Jira administrators can see it, and only when a Jira administrator has allowed space-level settings.
Still stuck
Note the work item key, the tracking number, and what the Waybill panel shows, then contact your app administrator or the app's support contact.