This blog post contains guidance for troubleshooting potential issues with the Contentstack SaaS headless content management system. There are many different kinds and causes of potential issues; not all these suggestions apply in every case. Some of this guidance may apply to troubleshooting any system, but especially service-oriented applications on SaaS. If you have additional suggestions for troubleshooting service-oriented SaaS solutions, headless CMS, or Contentstack specifically, please comment on this blog post.
First Things First
Almost every time that I have a problem with a system, the system behaves as instructed; the problem is with the instructions. Still, assume that any issue will result in a support case, although with the goal of finding the problem before support does, and preferably before contacting support.
Take notes about the troubleshooting actions that you attempt.
Copy text to a file, include screen shots, and capture video of the issue if possible.
Note the time the issue first appeared, how it appeared, and whether its appearance changes.
Indicate the intention of the attempt that results in the issue.
Write a reproduction scenario.
The most recent changes are most likely to have introduced the issue. Evaluate those changes applied most recently first.
While troubleshooting, avoid making additional configuration changes that could further complicate root cause analysis.
Contentstack System Status
Consider the possibility but avoid assuming issues with vendor products or network conditions and focus on errors in configuration, code, and other variables that you have introduced. At the same time, rule out the largest category of most unlikely errors, which is the CMS itself. You can check the system status by clicking the question mark (?) icon in the Contenstack UI.
Check the status of other systems on which your solution depends.
Postman
You can use Postman to troubleshoot APIs. Sometimes, just trying to enter the required parameters into postman can indicate the error. Other times, the response visible in postman is easier to process than that visible in code such as when calling the API from a browser. JSON results visible in Postman are also useful for diagnosing issues as well as copying for support cases.
Contentstack provides collections of preconfigured API requests for Postman.
Configuration
When an API call works in postman but not in code, ensure that the calling code uses the proper configuration to access Contentstack, specifically the API key for the stack, the name of a content delivery environment for that stack, and the delivery token for that environment.
Error Codes
If calling an API returns an error code, consider the possible causes for that code.
Firewalls
Where webhooks or calling APIs fails completely, beware of network firewalls that can block HTTPS API requests and webhooks. Specifically, when using webhooks, ensure that the webhook listener is exposed to the public internet, potentially using a reverse proxy such as ngrok.
Publishing
Especially when expected data does not appear, consider publishing. Ensure that the entries meet all required publishing rules for the required content delivery environment, ensure that they are not scheduled for future publication, publish the entries to the environment, check the publishing queue, and check the publishing status of the entries for that environment.
Search Indexes
When issues occur in solutions that depend on external search services, rebuilding search indexes may restore site functionality while investigating for the root cause of the issue.
Paging
When API calls result in more than the maximum number of entries, the system returns results in pages, defaulting to 100 entries per page. Retrieving more than 100 entries requires calling the API multiple times with parameters to control paging. If not all available entries appear in user interfaces or processing seems to ignore entries, consider whether paging may be a factor, and enhance code as required to support paging through results. For maximum performance, you may want to use threading to retrieve multiple pages simultaneously.
Logs
Review the audit log available through the Contentstack UI. If your solution maintains custom logs, evaluate those as well.
API Rate Limitations
If you receive error messages indicating that you have reached API or other rate limits for your Contentstack hosting plan, contact Contentstack to review your options.
Contact Support
If you cannot resolve an issue, you can contact Contentstack support, which is well-known for being responsive and helpful. To contact support, you can click the question mark (?) in the Contentstack UI or send an email to an address at contentstack.com that you can probably guess. Indicate the intention of the attempt, the reproduction scenario, and the results. Describe any changes implemented before the issue occurred. Include any relevant code. Include access credentials, specifically the API key for the stack, the name of a content delivery environment for that stack, and the delivery token for that environment. Include any error messages, links to screen shots and captured video, or anything else that might assist in analysis. Indicate when the issue first appeared, how it appeared, and whether its appearance has changed. Describe results from troubleshooting that you have attempted.
Deliverystack.net 