How to Troubleshoot MSI Error 1603: Fatal Error During Installation
MSI is a Windows Installer package format that uses Microsoft’s Windows Installer service to manage the installation (and uninstallation) of applications.
Although Windows Installer is a mature technology, you can still encounter errors when trying to install an MSI package.
One of the most common errors is Error 1603, which can be triggered by a variety of issues.
In this article, we will explore the potential causes of error 1603 and provide troubleshooting steps to help you quickly identify the root cause of the error and resolve it.
What is error 1603 and what causes it in Windows Installer?
The Microsoft Windows Installer (MSI) generates error code 1603 when it has trouble installing a software package due to an issue with either the Windows Installer or the software package.
As you can see, the error message doesn't provide much information and doesn't offer any hints on where to begin troubleshooting.
If you click “OK”, the installation rolls back.
Alternatively, if you've created a log file for the installation and you scroll down to the end of it, it should look like the one below:
MSI (c) (B0:98) [20:07:25:036]: MainEngineThread is returning 1603 === Verbose logging stopped: 01/02/2023 20:07:25 === |
|---|
Error 1603 can be caused by several common issues such as:
- Windows Installer is trying to install an application that is already installed.
- The installation folder of the application is encrypted.
- There are insufficient permissions to access the location where the software is being installed.
- Short file name creation is disabled.
- Conflicts with other software or services that are running on the computer.
- Conflicts with antivirus or other security software.
- Corrupted Windows Installer.
- Corrupted installation package.
- Unable to access install files in case of a web installer due to network and firewall blocks.
For more information and tips on how to resolve the 1603 error code generated by any of the causes above, check out MSI installation error 1603 - Windows Server | Microsoft Learn page.
MSI Installation Error 1603 - A Deep Dive into the Most Common Cause: CustomAction
The most frequent reason for error 1603 during MSI installation is a failed action, which is more likely to be a CustomAction rather than a Standard Action.
Let’s suppose we have an MSI that includes a VBScript file (MyCA.vbs) as a file in the File table. In this case, the VBScript is executed via a CustomAction which is set before the InstallFiles action within the InstallExecuteSequence table.
If we attempt to install this MSI, it fails with error code 1603.
Now let’s see how we can troubleshoot this error and find out which is the CustomAction that fails.
How to Troubleshoot 1603 MSI Error Code: Finding the Failed Custom Action
When the 1603 error “Fatal Error During Installation” is encountered, the first and probably the most important step is to determine which Custom Action has failed.
This can be easily achieved if we take into consideration that each CustomAction must return a value if msidbCustomActionTypeContinue return processing option is not set.
The possible Custom Action return values are:
Return value code | Return value | Description |
|---|---|---|
0 | ERROR_FUNCTION_NOT_CALLED | Action not executed. |
1 | ERROR_SUCCESS | Completed actions successfully. |
2 | ERROR_INSTALL_USEREXIT | User terminated prematurely. |
3 | ERROR_INSTALL_FAILURE | Unrecoverable error occurred. |
4 | ERROR_NO_MORE_ITEMS | Skip remaining actions, not an error. |
To troubleshoot the 1603 error, follow these steps:
1. Generate a verbose log file by using one of these methods:
a. using /l argument - /l*v to generate a verbose log file that offers detailed information about the installation.
b. enabling Windows Installer logging to generate a verbose log file that offers detailed information about the installation..
2. Open the verbose log file and search for the string “return value 3” - 3 is the return value code for when an unrecoverable error occurred.
3. Review the content of the log file located immediately above the “return value 3” string to determine which CustomAction has failed.
Different Resolutions for Different CustomAction Failures
While identifying the CustomAction that causes the Windows Installer to fail may be a straightforward process, the resolution to the issue can vary depending on the specific scenario.
In our example above, the installation failed because MyCA.vbs was added as a file within the MSI and the CustomAction that executed this VBScript file was set to be executed before InstallFiles action.
In other words, the CustomAction was trying to execute a script which was not installed on the target device at that time during the installation.
In this instance, the solution was to change the execution order of the CustomAction to a later point in the InstallExecuteSequence.
Conclusion
When encountering the MSI Error 1603, try searching for return value 3 to speed up the investigation process. By doing that, you will be able to identify the CustomAction that caused the Windows Installer installation to fail.
However, keep in mind that this solution can vary from one scenario to another and may require further investigation. We hope you found this article helpful.
FAQ: How to Troubleshoot MSI Error 1603
What is MSI Error 1603, and what causes it?
MSI Error 1603 is a generic Windows Installer error indicating a fatal error occurred during installation. This error can be triggered by various issues, including:
Attempting to install a program over an existing version without proper removal.
Insufficient permissions to access certain files or folders.
The installation path is encrypted or inaccessible.
Conflicts with running background applications.
Custom actions in the installer failing due to incorrect sequencing or conditions.
Identifying the specific cause requires examining the installation logs and system configuration.
How can I troubleshoot and resolve MSI Error 1603?
To address MSI Error 1603, consider the following steps, which can help resolve the error and allow the installation to proceed successfully:
Review Installation Logs: Search for "Return value 3" in the MSI log files to pinpoint the action that failed.
Check Custom Actions: Ensure that any custom actions in the installer are correctly sequenced and have the necessary conditions met.
Verify Permissions: Confirm that the user has sufficient permissions to install the application and access required directories.
Close Background Applications: Terminate unnecessary background processes that might interfere with the installation.
Ensure Sufficient Disk Space: Make sure there is enough free space on the target drive for the installation.
Avoid Encrypted or Network Paths: Install the application on a local, unencrypted drive to prevent access issues.
How can I identify the specific cause of Error 1603 in the installation logs?
To pinpoint the exact cause of Error 1603, use this approach to help you diagnose the issue by revealing the exact step where the installation encountered a problem:
Enable Verbose Logging: Run the installer with verbose logging enabled to capture detailed information.
Search for "Return value 3": In the generated log file, search for the phrase "Return value 3" to locate the point of failure.
Examine Preceding Lines: Review the lines above "Return value 3" to identify the custom action or process that failed.
Analyze Error Messages: Look for specific error messages or codes that provide insight into the failure.
Written by
Horatiu Vladasel
Horatiu is a Software Packager/Sequencer with over 10 years experience, who has worked as a Software Packager at IBM and is currently offering software packaging services to companies such as BT or Nationwide.