Troubleshoot Deployed Application Failures

Issue

Errors you encounter when running an application created using MATLAB® Compiler™ can indicate an issue with the MATLAB code being compiled or the deployment environment. For a general overview of application deployment, see Steps for Deployment with MATLAB Compiler.

Possible Solutions

After you compile your application, test the application on the development machine using the same version of MATLAB that was used to create the application. If your application executes only within MATLAB, the system library path might not be set correctly. For details, see Set MATLAB Library Paths for Testing Deployed Applications.

If the application works on the test machine, you can isolate failures in end user deployment. Typically, the target machine does not have a MATLAB installation and requires MATLAB Runtime to be installed. For more information, see About MATLAB Runtime.

Resolve Error: Missing DLL

Error messages that indicate missing DLLs, such as mclmcrrtX_XX.dll or mclmcrrtX_XX.so, are generally caused by an incorrect installation of MATLAB Runtime. For information on installing MATLAB Runtime, see Download and Install MATLAB Runtime.

Occasionally, you might encounter a version mismatch between a DLL included with both MATLAB Runtime and Microsoft® Windows®. You can use the Process Monitor tool to investigate which DLLs are called by your application. For information on using Process Monitor with your deployed application, see How can I use Process Monitor to troubleshoot the execution of my program?

Another possibility is that MATLAB Runtime is installed correctly, but the system library path is set incorrectly. For information on setting the path on a deployment machine after installing MATLAB Runtime, see Set MATLAB Runtime Library Paths for Deployment.

Caution

Do not move libraries or other files within the MATLAB Runtime folder structure. The MATLAB Runtime system is designed to accommodate different MATLAB Runtime versions operating on the same machine. The folder structure is an important part of this design.

Check for Excluded Files and Functions

MATLAB Compiler uses a dependency analysis function that determines all the files and functions on which the supplied MATLAB files, MEX-files, and P-files depend.

Functions that are not explicitly called in your application code must be included at compile time using one of the following: the %#function pragma, the AdditionalFiles property of a compiler.build function (such as compiler.build.standaloneApplication), or the mcc -a option. If the MATLAB file associated with a p-file is unavailable, the dependency analysis process cannot discover the p-file dependencies. Also, you must manually add support files such as .mat, .txt, or .html files. For more information, see Include and Access Files in Packaged Applications.

To find functions in your application that need to be listed in a %#function pragma, search your MATLAB file source code for text specified as callback character arrays or as arguments to the functions feval, fminbnd, fminsearch, funm, and fzero or any ODE solvers.

MATLAB and associated toolboxes have limitations on the functionality that can be compiled. For details, see Limitations for MATLAB Compiler. Ensure that the functions used in your application's MATLAB code are valid. Check the file mccExcludedFiles.log on the development machine. This file lists all functions called from your application that cannot be compiled.

Resolve Error: Unknown Function in Callback

If the dependency analysis process is unable to include a function used in a callback, your compiled application might not function correctly, or might issue an error message similar to the following example.

An error occurred in the callback: change_colormap 
The error message caught was    : Reference to unknown function 
                change_colormap from FEVAL in stand-alone mode.

The dependency analysis process cannot discover function calls located in either of the following:

  • Callback string

  • Character array passed as an argument to the feval function or an ODE solver

    Tip

    Dependent functions can also be hidden from the dependency analysis process in .mat files that are loaded by compiled applications. You might need to manually include .mat file classes or functions that are supported by the load command.

For deployed code, specify callbacks as character arrays or with function handles.

To find text used as a callback character array, search for the characters “Callback” or “fcn” in your MATLAB file. This search finds all the Callback properties defined by graphics objects, such as uicontrol and uimenu. In addition, the search finds the properties of figures and axes that end in Fcn, such as CloseRequestFcn, which also support callbacks.

Specify Callbacks as Character Arrays.  Create a list of all the functions that are specified only in callback character arrays and pass these functions using separate %#function pragma statements. This action overrides the product dependency analysis to explicitly include the functions listed in the %#function pragmas.

For example, the call to the change_colormap function in the sample application my_test illustrates this problem. To make sure MATLAB Compiler processes the change_colormap MATLAB file, list the function name in the %#function pragma.

function my_test()
% Graphics library callback test application

%#function change_colormap

peaks;

p_btn = uicontrol(gcf,...
                 'Style', 'pushbutton',...
                 'Position',[10 10 133 25 ],...
                 'String', 'Make Black & White',...
                 'CallBack','change_colormap');

Specify Callbacks with Function Handles.  To specify the callbacks with function handles, use the same code as in the example above, and replace the last line with:

'CallBack',@change_colormap);

Obtain Write Access to Install Directory

The first operation attempted by a compiled application is to extract the deployable archive. If the archive is not extracted, the application cannot access the compiled MATLAB code, and the application fails. If the application has write access to the installation folder, the software creates a subfolder named application-name_mcr the first time you run the application. After this subfolder is created, the application no longer needs write access for subsequent executions.

Resolve Error: Cannot Create Output File

If you receive the following error, there are several possible causes to consider.

Can't create the output file filename

Possible solutions include:

  • Obtain write permission for the folder where MATLAB Compiler is attempting to write the file (most likely the current folder).

  • Clear disk space in the folder where MATLAB Compiler is attempting to write the file (most likely the current folder).

  • Clear a running process that is blocking MATLAB Compiler. If you are creating a standalone application and testing it on the same machine, a process that is running might be blocking MATLAB Compiler from overwriting it with a new version. To clear the process, close instances of MATLAB or the application using your system task manager.

Use Multiple MATLAB Versions

Executables generated by MATLAB Compiler are designed to run in an environment where multiple versions of MATLAB are installed. Some older versions of MATLAB might not be fully compatible with this architecture.

On Windows, in the PATH environment variable on your machine, ensure that the path matlabroot\runtime\win64 in the version of MATLAB in which you are compiling appears ahead of the paths of other versions of MATLAB installed on your machine.

Similarly, on UNIX® systems, ensure that the dynamic library paths match. To do so, compare the outputs of !printenv at the MATLAB prompt and printenv at the shell prompt. For more information, see Set MATLAB Runtime Library Paths for Deployment.

The feature that allows you to install multiple versions of MATLAB Runtime on the same machine is not supported on macOS. When you receive a new version of MATLAB, you must recompile and redeploy all your applications and components. Also, when you install a new version of MATLAB Runtime on a target macOS machine, you must delete the old version of MATLAB Runtime before installing the new one.

Deploy Newer Version of Application

When deploying a newer version of an executable, you must redeploy the executable because it also contains the embedded deployable code archive. The deployable archive is keyed to a specific compilation session. Each time an application is recompiled, the software creates a new, matched deployable archive. Delete the existing application folder and run the new executable to ensure that the application can expand the new deployable archive. You must have write access to expand the new deployable archive.

See Also

Topics