Skip to main content
Matrix42 Self-Service Help Center


Question: After successful import and variable declaration I assigned the SimpleOsDeployment package (or any other package) and activated the client, but the package does not start, and the operating system is not installed.

Answer: Please make sure that the SimpleOsDeployment package (or any other package) has been approved for installation.


Question: The client seems to have errors while executing and restarts the whole time. How can I prevent it from restarting so I can see what fails?

Answer: On the client the PE agent is executed which executes the PreOS packages. If an error occurs, a reboot is always performed, so that an error package is loaded again and again, and the client restarts again and again. The PE-Agent has its own configuration file, with which you can deactivate the reboot to debug the problem (Matrix42.Empirum.PeAgent.dll.config). The switch "EnableReboot" must be set to "False" to disable restarts. With the switches "DelayOnErrorInSeconds" and "DelayRebootInSeconds" you can also delay the execution in case of an error or before restarts (specified in seconds).


A simpler option is to use the Matrix42 PreOS package DebugPackage. The package must be assigned to the client, the client must be activated and rebooted. The DebugPackage package disables the reboot of the PE agent so that after execution (successful or incorrect) of the assigned packages the PE agent does not reboot the client.

The Matrix42 PreOS package DebugPackage requires a PE Agent version 1.3.0 or higher.

Question: When importing a Matrix42 PreOS package, the package does not end up in the register from which I started the import. What can I do?

Answer: Matrix42 PreOS packages are always imported into the register specified in the configuration file (EmpirumPackageData.xml) of the package. This behavior differs from the behavior when importing software packages. If you start the import there via a special register (for example, Software), the imported software packages are also added to this register. If you want to change the register in which the Matrix42 PreOS package should land, you must change the file EmpirumPackageData.xml in the XML node SoftwareDepotRegister.

Question: The domain join no longer works with the new Windows installation 4.0 package. What can I do?

Answer: As of version 4.0, the Windows installation package no longer contains the functionality of the Domain Join. The domain join has been moved to its own PreOS package called "DomainJoin", which now must be assigned and configured additionally. The advantage now lies in the fact that the status of the domain join can be better checked. The status of the new domain join package should provide information about the status of the domain join.

Question: Domain Join fails: "2224 - The account already exists". What can I do?

Answer: The DomainJoin package is not designed to move a computer from an already assigned OU. This means that the computer was already assigned in an OU and that this OU differs from the one currently configured. Either you check the ORGANIZATIONAL_UNIT variable and make sure that the OU has been configured correctly or you remove the computer from the OU in Active Directory (Domain Controller).

Question: The Empirum Agent is no longer installed after using the new Windows installation 4.0 package. What can I do?

Answer: Starting with version 4.0, the Windows installation package no longer contains the functionality to install the Empirum Agent. The installation of the Empirum Agent has been moved to a separate PreOS package called "EmpirumAgentSetup", which now must be additionally assigned and configured. The advantage is now that the status of the Empirum Agent installation can be better checked. The new package also interprets the variable MX42_AGENT_PUSH_PACKAGE_FOLDER.Windows to determine which Empirum Agent version to install.

Question: An error occurs when importing a Matrix42 PreOS package. What can I do?

Answer: Older versions of a package may contain incompatible variable definitions which cannot be updated during the import. First delete all older versions of the package, including the incompatible variable definitions, and try restarting the import. Please note that the variable values of this package must be reset.

Question: When attempting to deploy a computer via WinPE based deployment, the PXE boot of the WinPE image will abort frequently. Is there a way to stabilize the transfer?

Answer: The TFTP block size setting can be used in the boot configuration to try to make the transfer more stable. A small block size reduces the risk that the transfer of each block is aborted but usually leads to a slower transfer of the image.

Question: When attempting to determine the manufacturer and model of a computer using the HardwareInfo package, I have the problem that the computer cannot establish a connection to the Empirum server and therefore cannot execute the HardwareInfo package. Is there a way to get the information without the HardwareInfo package?

Answer: Yes. Each WinPE image contains a tool DriverInfo.exe in the UAF directory, which can be executed after booting on the computer even without network connection. The tool gives information about the devices and their driver supply on the computer and writes the information into a log file DriverInfo.exe.log in the UAF directory. The first lines of this log contain the manufacturer name and the model name.


Question: While executing Windows setup running WindowsInstallation package an error like 'unable to locate an existing system partition' appears. How should I handle this?

Answer: If there are several hard disks and already a Windows installation on the device, and another disk has been selected as the system hard disk. Using the 'PreferFastDisk' for example - then it can lead to problems. You can either clean all disks manually via DISKPART or via the hidden variable 'ClearAllDisks' when running the DiskPartitioning package. You must add the variable "ClearAllDisks" as number to variable DiskPartitioning under "Tools > Variable Definitions..." in EMC and set it to 1.

Question: If WinPE image creation fails and the BTQH log contains an error that is something like "Start Windows PowerShell with the Run as administrator option, and then try running the script again" (German: "Starten Sie Windows PowerShell mit der Option "Als Administrator ausführen", und versuchen Sie noch einmal, das Skript auszuführen"). What can I do?

Answer: The user account under which the BTQH Service runs must have administrative rights (e.g. a member of the Administrators group). Please make sure that this user is a member of the Administrators group to avoid this error.

Question: When creating a Computer Self Provisioning activated WinPE image there is an error. The error message "Error at validating Empirum API server settings" can be found in the log of the BTQH service. What can I do?

Answer: The error message indicates that the settings of the Empirum API service cannot be read. Make sure that the Empirum API service is configured and installed via Matrix42 DBUtil. Also make sure that the HTTP protocol is used, because only this is currently supported by Computer Self Provisioning.

Question: How can I customize the default language of the WinPE Self Provisioning user interface?

Answer: In the file "Matrix42SelfProvisioningUI.exe.config" under  .\Empirum\EmpInst\Sys\Images\WinPE\binaries\UAF\ at the bottom there is the value <add key="DefaultLanguage" value="English"/>. This value can be set to the desired language "Deutsch / English / Francais".


Question: Can I manually add data to the newly created WinPE USB flash drive?

Answer: Since WinPE version 1.6.5 and higher creates two partitions on the USB flash drive, the second NTFS partition can be filled manually with the data - operating system files, language packages and drivers - from the Empirum Share.

The USB flash drive has the same structure as the installation directory. The added data must also be stored in the same place on the USB flash drive as they are stored in the installation directory.

Question: In the boot configuration all controls are grayed out. I cannot create or change a boot configuration. What can I do?

Answer: To create or change boot configurations the logged in user requires the role EMP_I_DISK_CONFIG. If the user does not have the required role, the control elements are grayed out and the existing configurations can be viewed only. To change the boot configuration, log on to the Matrix42 Management Console with another user or use the user management in Matrix42 DBUtil to assign the role EMP_I_DISK_CONFIG to the logged-on user.

Question: The operating system installation via HTTP(S) fails, error 403 is displayed. What can I do?
Answer: If this error message is displayed, the specified user does not have write access to directory structures in IIS.
See also Setting up WinPE based deployment via http(s).

Question: The operating system installation via HTTP(S) runs without problems, but there are some errors 404 in the Matrix42.Platform.Service.Host.log. What is the reason for this?

Answer: Currently, the error 404 also appears in the log file of a successful deployment. The reason for this is a generic approach to transferring directories and single files. If a single file is to be transferred, it is initially treated as a directory. The transport first tries to identify the contents of this directory. This leads to the error 404, because a corresponding directory does not exist. The error message is then as follows:
[Error] [JobProcessorBase.Execute] The remote server returned an error: (404) Not Found.
This error message is followed by another warning:
[Warning] [HttpTransfer.RunGenerateList] Issue at running list job. Message: The remote server returned an error: (404) Not Found.
The following is a reminder that the transfer is now tried with a single file:
[Information] [HttpTransfer.TransferFromServer] Could not list content of '\DeviceMapping.xml'. => Try to transfer single file.
This transfer is then performed successfully.
[Information] [HttpTransfer.StartTransfer] Final status: 'Finished'

Since WinPE Support version 1.8.5 these error messages do not occur anymore.

Question: The operating system installation via HTTP(S) fails when transferring the DeviceMapping.xml The network card is not yet addressable. Is there a way to configure the number of connections retries?

Answer: The number of connections retries can be set in the PE Agent configuration file Matrix42.Empirum.PeAgent.dll.config. The file is in the EmpInst$\Sys\Images\WinPE\binaries\UAF directory. The OpenConnectionRetries value specifies the number of connections retries and is set to 10 retries by default.

If the value in the Matrix42.Empirum.PeAgent.dll.config is changed, the Boot Configuration used must be saved again so that the change is transferred to the PXE image.

Question: The operating system installation via HTTPS terminates with the error message "Thumbprint list is empty at Https case. What is the reason for this and what can I do?


Answer: The PE agent has tried to establish a transmission via Https. The option "Only trust validated server certificates" is selected in the agent template that is used. Since the usual validation using the certificate store and certificate chains does not work under WinPE, the PE Agent will perform the validation using the defined certificate thumbprints. But the list of thumbprints defined in the PE Agent configuration file Matrix42.Empirum.PeAgent.dll.config (in the EmpInst$\Sys\Images\WinPE\binaries\UAF directory) is empty. A secure connection could not be established.

Chapter  OS Deployment via http(s) describes in more detail how to get the thumbprint information using the IIS Manager and how to enter it into the configuration file. Finally, the boot configuration used must be saved again so that the change is applied to the PXE image.
If a check of the server thumbprint is not wanted, then the option "Only trust validated server certificates" must be deselected in the Agent Template. A connection can then also be established without a thumbprint.

Question: The installation of an additional disk works fine on Windows 10 systems, but on Windows Server systems this disk is marked as "Offline". What can I do?

Answer: You are using an unattend.xml with custom extensions based on an outdated template. Please use the current template or extend your old unattend.xml with the structure offlineServicing/Microsoft-Windows-PartitionManager/SanPolicy=1 as described below:



  • Was this article helpful?