How To Troubleshoot Windows Azure Mobile Services
- 31 May 2013
Undoubtedly when developing application using Windows Azure Mobile Services you will get unexpected results. This guide will help you isolate and troubleshoot the most common errors that you will encounter. This post is not intended to solve you issues but help you isolate and simplify the problem so you can dig in deeper or engage Microsoft Support for additional help. Also see: Mobile Apps Troubleshooting
Basic Architecture
To effectively troubleshoot a problem you need to understand how Mobile Services work. A simple breakdown of the architecture is that there is a server component (your Mobile Service URL) and a client component (your application code).
When you create your Mobile Service, we host your Service on Azure and expose an HTTPS endpoint that allows your client code to access your data stored in your Azure SQL database.
Your Mobile Service (the server component) is hosted on Azure and depends on our Azure infrastructure to bring up your Service when it is needed (if free mode… the default) and provides logging and other services like the Scheduler.
The client will issue one of five types of requests to the server. There is a login request and four data requests. The client communicates with the server through the REST API over HTTPS (or HTTP). If you are using Windows, Android, iOS or any other client, those libraries simply translate the client library code into an HTTPS call to the REST API. Understanding this API is your key to troubleshooting difficult issues! Here is a link to the REST API documentation. Watch Josh’s video on this API to learn how to login, create, read, update and delete data without writing any client code!
The server has a script interface for the four data operations. You can use logging in these scripts to determine if a request gets to your server and what parameters are being passed How to: write output to the mobile service logs. In addition you can run a Scheduler script on demand or on a schedule and there too, you can use logging to troubleshoot. Ultimately the scripts will communicate with your Azure SQL database. You can see your data in the DATA tab of your Mobile Service or connect to the Database through the portal and view it there.
Troubleshooting the Problem is Isolating the Problem!
You need to determine where you think the problem is; the Mobile Service infrastructure, your Mobile Service, Azure SQL or client code, and then compare what the expected result is verses what you are experiencing. Here are some steps you can take to isolate the problem:
Can you get to your Mobile Services dashboard (https://manage.windowsazure.com/) and click on your Mobile Service? If not, perhaps there is a connectivity or network error where you are.
Are the Mobile Services healthy? You can go to Windows Azure Service Dashboard and see if the Mobile Services are see the status. Click on the RSS feed icon on the right of the Mobile Services to see any news about Mobile Services. There is a link at the top of the page to get help if the service is not healthy.
Look in the LOGS tab of your Mobile Service in the Windows Azure Management dashboard (https://manage.windowsazure.com/) and see if there are any useful errors logged that give you a clue where to start looking. These logs are generated when there are errors or messages generated from the scripts you have defined for your mobile service or if there are problems executing the default script actions (Scheduler, insert, read, update or delete).
Look at your DASHBOARD. Have you exceeded your usage in any category? That will cause a 500 Error! The Free Tier has a limited amount of Outbound data (Free means development not a deployed app so you may need to upgrade).
Can you get to your Mobile Service URL? You can find this if you don’t know it if you click on your Mobile Service and look on the Dashboard tab for ‘MOBILE SERVICE URL’? If you cannot reach this URL there may be a problem with your network or Mobile Service. Your Mobile Service URL will be of the form https://MOBILESERVICENAME.azure-mobile.net. If you cannot get to your Mobile Service URL, turn off ‘Friendly Error Messages’ in Internet Explorer and see if you are getting a 500 (note: 500 error means anything in the 500 range) error back. If you get a message that you cannot connect that means there is an issue with your network. If you get a 500 error back that means something is wrong in your Mobile Service! The problem may be due to one of your scripts. This could be the Scheduler, insert, read, update or delete scripts for one of your tables. A quick test is to go to the configure tab and toggle the ‘ENABLE DYNAMIC SCHEMA’ property from its current value, save and then toggle it back and save. This will reset you Mobile Service instance. Immediately try the Mobile Service URL again and if you can get to it without the 500 error, one of your scripts is at fault (see debugging scripts). If that does not fix the 500 error look in your LOGS tab to see if there are errors logged that may help you troubleshoot further or contact Microsoft Support.
Cannot reach Mobile Service URL (network issue):
Successful test for Mobile Service URL:
Turn off Friendly Error Messages by unchecking this box:
If you can get to your Mobile Service URL and it reports that your service is up and running the problem may be your code, data or scripts is causing your issue. You can use Fiddler or your favorite ‘Man in the Middle’ https or http network inspection tool to troubleshoot this further. Your Mobile Service is accessible over HTTP or HTTPS so if you cannot find a tool to decode the HTTPS you can change your Mobile Service URL to point to the HTTP version of your site and use a tool like Netmon (Microsoft Network Monitor) or WireShark. For example: https://jeffcooldemo.azure-mobile.net/ is also reachable at the HTTP URL http://jeffcooldemo.azure-mobile.net/. Change your code to point to the http version and log the traffic! Here is an example of a response that was due to a script that was stuck in a loop. By removing the script temporarily we were able to confirm that indeed the script was the cause and we could put parts of the script back in to find the problem:
HTTP/1.1 503 Service Unavailable
Cache-Control: no-cache
Content-Length: 56
Content-Type: application/json
Server: Microsoft-IIS/8.0
Set-Cookie: ARRAffinity=a1609f7e18423e2e751820185650cd3294e23cc9124779bc6fa5cbbf3c204a6c;Path=/;Domain=jeffcooldemo.azure-mobile.net
x-zumo-version: Zumo.Main.0.1.6.2648.Runtime
X-Powered-By: ASP.NET
X-Powered-By: ARR/2.5
X-Powered-By: ASP.NET
Set-Cookie: WAWebSiteSID=aff2b3fa800f40f0ae32c899ca03029b; Path=/; HttpOnly
Date: Thu, 30 May 2013 13:00:43 GMT
{“code”:503,”error”:”Error: The request has timed out.”}
If you see a 401 error from Fiddler the problem is in your authentication. Find out from your DATA tab what the permissions are on the table you are trying to access. Adjust your code or permissions appropriately.
If Fiddler or similar tools do not reveal a specific error or problem (inspect both what you are sending and what you are receiving) you need to simplify the problem to determine if basic functionality is working for you. Use Composer in Fiddler or Postman in Chrome to manually retrieve your table information. Start simple and add complexity as you succeed with the simple operations. For example, can you fetch the entire table (see this post)? If not what does the dashboard show, can you see the data from your Mobile Services DATA tab? If you can see the data in the dashboard but fetching results in nothing or an error, then inspect the LOGS on the Mobile Service and/or temporarily put back the default ‘read’ script if you have modified it. Optionally you can bypass your scripts by using the X-ZUMO-MASTER header with your Master key and use the noscript uri parameter (see the Query documentation).
If the read operation works but the Insert, Update or Delete operations fail then follow a similar pattern: Check the LOGS, try restoring the default scripts (create a new Mobile Service to see what they were originally) and finally you can try some simple operations using the REST APIs and Fiddler or Postman. If restoring the scripts to the original scripts works, then you need to debug the problem script. You can do this using console.log(“message”) throughout the script or better yet see this post: Debugging your Mobile Service scripts.
Assuming you have proven to yourself the Mobile Service itself is performing correctly, you can move on to troubleshooting the Client application code.
Again, Fiddler is your hero here. Capture the traffic from your application and compare it to the successful cases when troubleshooting the server side. Are there query parameters or odd data? What is the client sending when you inspect the traffic in Fiddler and does it get a response back? Perhaps the Mobile Service is giving you back exactly what you are asking for but your client logic is filtering the data with the request. You can see detailed error messages in the response that may not be visible in your application. For example here is some output from a custom query that resulted in a 400 error. The 400 code is not useful but the JSON in the response (viewable in Fiddler) pinpointed the problem:
{“code”:400,”error”:”Error: Invalid query specified. Error: Unknown identifier ‘substringOf’ (at index 11)”}
If Fiddler does not show you what the problem is you can debug your code and see what is being returned and sent. Perhaps the problem has nothing to do with the Mobile Service client but with your logic after you get the response! Confirm you are getting the data back you expect using Fiddler and then start breaking down what you are doing with that data. You can create a new project that uses your Mobile Service and start with the simplest operations to isolate the potential issue.
Search the Forums. Chances are, someone else has faced the same problem you are! You can get to the Forums from the Azure portal. Mobile Services is currently in the Preview Forums here: http://social.msdn.microsoft.com/Forums/en-US/azuremobile/threads
Try the sample code and quickstarts to see what is different between your code and these documented working scenarios (again Fiddler can help you compare traffic between the success and failed cases).
Parting thoughts
Isolating the problem is critical for troubleshooting. If you ask for help on the forums or through support, you will be asked to narrow the problem to the simplest repro so you should do this on your own as you try to find where the problem is.
I will augment this post with new information and ideas for troubleshooting. Feel free to let me know if you have success with these steps or have suggestions for other troubleshooting steps! Do not expect support via this blog however. Make sure you post questions to the Mobile Services forum instead (I filter responses on my blog and won’t post support requests).
Jeff