Introduction
Many FME users are unfamiliar with web services and may find editing or creating web services in FME a more advanced task. Additionally, it is not always easy to discern the cause of a failed web service authentication in FME Form. Often, the web service provider returns an HTTP response and an error code, which can be useful for creating a successful web service and subsequent web connections.
This troubleshooting guide covers common errors encountered when users create web service definitions, along with the troubleshooting steps we often follow to identify the cause of failure.
This article is specific to FME Form. For troubleshooting on FME Flow, see the article FME Flow Troubleshooting: Web Connections
Checklist
Are you using the right type of web service?
FME supports OAuth 2.0, token, and HTTP. Your web service provider documentation should state what type of connection is used. See Web Connections and FME.
Have you correctly entered all of the information for the web service?
The web service documentation should show how to set up the web service definition, how the auth URL is formatted, whether you need to send a client secret, whether it has a refresh token URL, etc.
Have you tested the web service in a separate HTTP client?
Many web services show examples using Postman. If you can successfully get it working in another HTTP client (like Postman), then there is a high likelihood it should work in FME.
Have you cleared the cache?
Sometimes, when signing in to a web service to authenticate, you may be prompted to save credentials, or FME may cache settings such as the auth URL. If you're expecting a different behavior or outcome, it can be useful to clear the cache. To do this on the FME Toolbar, choose Tools > Purge Temporary Files. This will clear the cache for FME Form and allow you to re-test your web service.
Do a web search for any errors from web service providers.
If you see an error in the pop-up browser that FME launches for authentication from the service provider, a web search will likely return results explaining what caused the error. Web service provider documentation or sites like Stack Overflow will often return helpful results for error codes and error messages, allowing you to fix the issue.
Have you searched the FME Community?
For popular web services, you may find tutorial articles or forum questions that may help you resolve your issue.
Additional Troubleshooting
If you are still unable to identify the cause of an incorrect web service definition, here are some advanced troubleshooting steps you can take to analyze web traffic to and from the web service.
As FME uses QT (an application manager), QT interprets the responses from the web service being authenticated with. It is unlikely that you will see logs in the FME Form log window.
When you authenticate with an OAuth service, FME (QT) opens a browser window to prompt you to enter your credentials.
Since FME does not log requests or responses to the web service, you may need to use another method to analyze the traffic. Seeing the response from the web service can be very helpful when debugging an unsuccessful request.
QT debug
This option is good for checking that the authorization URL has been formed correctly based on how the web service definition has been set up, or if you are having issues with the browser window that FME opens.
If you wish to use the browser's developer tools to help troubleshoot, you can open FME with a remote debugging port. Any embedded browser windows will be accessible through your browser.
To do this, open FME Workbench with the --webEngineArgs and --remote-debugging-port flags. You will need to open a command-line tool and navigate to the location of the FME executable:
$ ./FME fmeworkbench --webEngineArgs --remote-debugging-port=8091
DevTools listening on ws://127.0.0.1:8091/devtools/browser/2598870a-f0b9-471a-8194-9789b6a80eadNavigate to http://127.0.0.1:8091 in your browser, and refresh the page once an embedded browser opens in FME. Here you can verify that the authorization URL is formatted correctly by comparing it with the documentation for that web service or with an HTTP client like Postman.
Clicking on the URL will open a developer tools window where you can inspect the network traffic. Click on the >> to view the Network tab.
If FME opened the authentication window in a normal browser window, you can open developer tools and inspect the network traffic.
When inspecting network traffic, it may be useful to check the request (to confirm it is formatted correctly) and the response (for any errors).
Fiddler
Fiddler is a web debugging proxy tool that makes it easy to inspect web requests FME sends to a web service and analyze the response.
If web service authentication or authorization fails during testing in FME, the displayed response is often uninformative and doesn’t explain why it failed. Web services should return an error code and a message that you can view in Fiddler.
An example of a response in FME Form:
Setting up Fiddler
Note: These screenshots are from Fiddler Everywhere. If you are on Windows, you may be able to use Fiddler Classic. The functionality should be the same, although the UI will be different.
Once Fiddler is installed and running, open the settings to see which port it is running on:
Configure FME to use a system proxy and ensure it uses the same port Fiddler is listening on.
Use Fiddler to analyze FME web traffic
You can filter Processes in Fiddler to only show traffic coming from FME:
If you now test your web service, you should see requests to that service appear in Fiddler.
The error in FME indicates that the web service was unauthorized, but it doesn’t explain why.
Clicking on that request in Fiddler (to login.microsoftonline.com) and then inspecting the response body confirms that this is due to a missing client secret. With this information, you can now correct your web service definition in FME and try again.
Additional Resources
Please consider posting to the FME Community Q&A if you are still experiencing issues that are not addressed in this article. There are also different support channels available.
Make sure to include as much information as possible:
- What web service are you connecting to? Include relevant documentation from that web service.
- What troubleshooting methods have you tried so far?
- Include any error messages.
- Screenshots of the web service definition and any setup on the web service provider end that may help identify any issues.