Troubleshoot Wowza Streaming Engine Media Cache

This article covers common errors that may occur when using Media Cache, a built-in caching mechanism included with Wowza Streaming Engine™ media server software that increases the scalability of video-on-demand (VOD) streaming.

Enable debug logging for Media Cache


Debug logging can help you resolve issues and gain insight into problems. When debug logging is enabled, all entries are written to the [install-dir]/logs/wowzastreamingengine_access.log file, including HTTP attempts and failures, when content is purged from the Media Cache store, and time taken to retrieve content. It also records warnings so that Media Cache operations can be traced in the log file.

You can enable debug logging either in Wowza Streaming Engine Manager or directly in the Server.xml file.

Note: Debug logging should only be used temporarily, for diagnostic purposes. Due to the increased load it puts on the server, it should not be used in a production environment.

Wowza Streaming Engine Manager configuration

  1. In Wowza Streaming Engine Manager, click the Server tab.
  2. In the Server contents panel, click Server Setup.
  3. Click the Properties tab.
  4. In the Quick Links section, click Custom.
  5. Click Edit, and then click Add Custom Property.
  6. Enter the following information in the Add Custom Property dialog box:
    • Path – Select /Root/Server.
    • Name – Enter MediaCacheDebugLog.
    • Type – Select Boolean.
    • Value – Enter True.
  7. Click Add.
  8. Click Save, and then restart the server to apply the changes.

Server.xml configuration

  1. In a text editor, open the [install-dir]/conf/Server.xml file and locate the <Server>/<Properties> container.
  2. Copy the following property into the container:
    <Property>
        <Name>MediaCacheDebugLog</Name>
        <Value>true</Value>
        <Type>Boolean</Type>
    </Property>
    
    
  3. Save and close the file, and then restart Wowza Streaming Engine.

Media Cache store errors


If Media Cache can't write to the defined store location, Wowza Streaming Engine displays the following error after it starts:

Media Cache failed to start
MediaCacheImpl.start[MediaCache]: Store not added to Media Cache. Directory not found: /mediacache/temp
MediaCacheImpl.start[MediaCache]: No stores could be added. Media Cache is not usable.

To resolve this error, make sure you have permission to read and write to the store location and that you have enough disk space to hold the cache.

MediaCache.xml file missing


If Wowza Streaming Engine can't find the MediaCache.xml file, it displays the following error:

MediaCacheImpl.start[Media Cache]ERROR server comment - MediaCacheServerListener.loadConfig: MediaCache.xml missing: /usr/local/WowzaStreamingEngine/conf/MediaCache.xml
MediaCacheImpl.start[Media Cache]: No stores could be added. Media cache is not usable.

To resolve this error, make sure that MediaCache.xml is located in [install-dir]/conf/.

Operating system considerations


Disk allocation

On Linux operating systems, you may see a discrepancy between what Wowza Streaming Engine reports as the disk utilization/fullness of the cache disks and what's reported by the operating system.

  • Media Cache pre-allocates the entire file size when an item enters the cache, and then fills the file in chunks based on what was viewed. If you add up all of the file sizes of the individual chunks on the disk, you'll see that this number matches the value reported by Media Cache.
  • Linux only allocates a disk block at the OS level when it's used. For example, if the file size is 100 MB, the OS reports 10 MB used if only the first 10 MB are filled. You'll see this discrepancy if you have a high level of abandonment, where viewers only watch the beginning of most files.

Media Cache performance on Windows and macOS

Media Cache may not perform as expected when running on Windows or macOS. If you encounter problems, try running Media Cache on Linux with the version of Java that automatically installs with Wowza Streaming Engine.

More resources