Troubleshooting WOPI API with The Cloud Storage Partner Program

This article examines common problems with implementing a WOPI API and host, looking at the best development practice to minimise your problems. We take you step by step through the troubleshooting process, with a closer look at wopitest and how the cloud storage partner program could help you.

Remember, implementing WOPI for the first time is quite daunting, so if you need assistance, please get in touch with us to find out how our experts can help. You can also find official Microsoft WOPI troubleshooting information on the Microsoft website.


The main difficulty with WOPI troubleshooting is that the WOPI client does not give useful error messages, and so you should build extensive logging into your WOPI API implementation. It will really help you track down problems! Most of the time, these types of problems are caused by errors in your API implementation, with errors rarely on the Microsoft side.

The errors you will see in the WOPI client are usually an error message, i.e. “Sorry, there was a problem and we can’t open this document. If this happens again, try opening the document in Microsoft Word.” Or bizarre JavaScript errors in the developer console!

Step 1 – .wopitest Validation

Get the .wopitest validation working. If you don’t have these tests working, then your API implementation is unlikely to work. However, having these validation tests working does not mean that your API implementation will work, as the tests are not exhaustive. For example, the SHA256 test only checks that you are supplying some text in the SHA256 property of CheckFileInfo. It does not check that the SHA256 is valid! Therefore, if you have your SHA256 calculation wrong, the validation test will pass, but the WOPI editor will fail to load with a strange JavaScript error.

Step 2 – Known Issues

Next, be sure to check ‘Known Issues’, which can be found on the Microsoft Documentation page.

Step 3 – Detailed WOPI API Debugging

Before reporting a problem to Microsoft, you should check the log of your own WOPI implementation for errors and warnings first. Look for Exceptions, 500s and other unexpected responses. Most of the problems we see in here that get reported to CSPP are because of a failure at the host side, not the Microsoft side.

Typical problems are:

   1. The domain for your WOPI API is not on the test allow list

   2. You are not providing OwnerId in CheckFileInfo

  3. You are not providing Size in CheckFileInfo

   4. You are not providing a valid SHA256 in CheckFileInfo

   5. You are not providing a Version in CheckFileInfo

   6. You are not providing a valid LastModifiedTime in CheckFileInfo

   7. You are providing additional unexpected properties in CheckFileInfo

   8. You are not providing the required properties in CheckFileInfo

   9. You are not handling Locks correctly

   10. Incorrect proof key validation implementation

   11. access_ttl expired

In our experience, most of our clients’ problems are with their initial response to CheckFileInfo, so you should go through that very carefully.

At this point, it’s a slow process of checking each individual property for all of your WOPI API calls to make sure that they conform exactly to the documentation. A good place to start is here. Although it’s a slow process doing this, requesting support from CSPP can be slower (they are super-busy!)

Another top tip is to check in your log the last operation that Microsoft called in your WOPI API. It can be a good guide to sorting out problems. Sometimes the last response you sent to Microsoft was the incorrect one! For example, if that last operation called was “Lock” and no further calls were made, there’s a good chance that there was a problem with your Lock response.

Step 4 – Help from The Cloud Storage Partner Program

Finally, for help from Microsoft, you should provide Microsoft with a Fiddler trace and a session ID. Be aware that it may take two weeks or more to get a reply. The reply is generally something like “You did not supply OwnerId in CheckFileInfo”, so it’s much quicker if you can debug it and find the issue yourself!

For more information on WOPI, including using WOPI to embed Microsoft Word, please take a look at our blog posts covering these topics in detail. Or, please contact us to find out how we can help you with your WOPI Integration. 

Nick McKenna
Since 2004, Nick McKenna, BSc, MBCS Biography has been the CEO of McKenna Consultants. McKenna Consultants is a bespoke software development based in North Yorkshire, specialising in Cloud development, mobile App development, progressive web App development, systems integration and the Internet of Things development. Nick also holds a First Class Degree in Computer Science (BSc) and wrote his first computer program at the age of nine, on a BBC Micro Model B computer. For the last 21 years, Nick has been a professional computer programmer and software architecture. Nick’s technical expertise includes; Net Core, C#, Microsoft Azure, Asp.Net, RESTful web services, eProcurement, Swift, iOS mobile development, Java, Android mobile development, C++, Internet Of Things and more. In addition, Nick is experienced in Agile coaching, training and consultancy, applying modern Agile management techniques to marketing and running McKenna Consultants, as well as the development of software for clients. Nick is a Certified Enterprise Coach (Scrum Alliance), SAFe Program Consultant (SAI), Certified LeSS Practitioner (LeSS) and Certified [email protected] Practitioner. Outside the office, Nick is a professional scuba diver and he holds the rank of Black Belt 5th Dan in Karate.

Posted in: Tags: