Merlin Troubleshooting

Encountering challenges during the SDK installation with Merlin is not uncommon. We outlined several prevalent issues that users may confront.

Accessing log files

Merlin Logfile is located in this following path:

%APPDATA%\Merlin\log\combine.log

Unable to download Merlin

Failure to download Merlin is due to your company policy restricting untrusted files. Speak with your IT.

Unable to install Merlin

Once you have downloaded Merlin, you will need to click on the downloaded file to install Merlin. If for any reason this is failing, it means your firewall or antivirus is blocking the installation process. Double check your AV and stop it.

Merlin fails to start

Double check your OS. Certain OS are not support on Merlin. Visit our Software guide regarding OS support.

Hardware check issues

Hardware check is one of the first prerequisite checks Merlin does before you are able to proceed to install the SDK. The hardware check is ensuring you have the minimum specifications required to run the SDK.

If any of the hardware checks are failing, double check your machine specs and retry.

Dynamic Memory and CPU allocation does not work in VM, if you are on VM, ensure you have this turned off and CPU & Memory set to the required amount.

If you are unsure what the requirements are, those can be found here.

Double check your hardware specs:

Dynamic Memory and CPU allocation does not work in VM, if you are on VM, ensure you have this turned off and CPU & Memory set to the required amount.
Double check your internet connectivity

If you are failing the Feeds Check, it means Merlin is unable to establish connectivity to Feeds.

It could either mean your firewall is blocking the request, some IT restrictions are in place that is preventing Merlin from downloading packages from Feeds or your feeds account does not have permission to download from Feeds.

In some cases, if you have proxy server in place, it will block any requests made from Merlin. If this is the case, reach out to a SDK Team member for a possible work around.

Double check by manually going into Feeds, and download any package.

Software check issues

There are 3 important pieces of software that Merlin checks:

Visual Studio 2022
SQL Server 2022
Chocolatey 1.4.0.

Merlin will automatically install any of these if you do not have them installed, HOWEVER in the case you do have them installed, Merlin will CHECK to ensure you have the right version installed.

If you are unable to get this check checks to pass, the easiest approach is to completely uninstall the software and restart Merlin and have it automatically install the missing Software for you.

If the preq. check is failing for visual studio, it means you are missing one of these Workloads or Individual Components. Ensure you have these installed.

Required workloads
Required individual components

Jira API Key Setup

If you are being redirected to the Jira Set up screen after setting up the Jira API Key in settings, this is because the key you are providing is incorrect.

Uninstall

Uninstall SDK can be accessed via the Settings page. This will uninstall ANY traces of the SDK. (Chocolatey packages, App pool, Orb folder..etc)

It will not remove any of the softwares (VS studio, sql..etc)

If you encountered an issue during the SDK installation process, it is highly recommended you Uninstall the SDK first and retry.

Merlin on Microsoft Windows Server 2022 Datacenter Azure Edition

Merlin Installer (and many other software installers) may exit abnormally after launch without prompting for UAC or proceeding with install when run while logged in as the local “BuiltIn\Administrator” account.

In Azure (and possibly other cloud providers), this account is likely to be renamed as part of some deployment processes. You can determine which account is the “Builtin\Administrator” account by running in Powershell:

Get-LocalUser | ? {$_.SID -like "*-500"}

Create a new account (local or domain) on the system and add it to the Local Administrators group (or otherwise provide it with admin access). Use this other admin account instead of the BUILTIN\Administrator account for software installation / development.

EBUSY: resource busy or locked

If you are seeing this error in your combine.log file. it means that you have an antivirus running and its scanning the downloaded files and locking it, which is preventing Merlin from unzipping and installing.

Temporarily disable your AntiVirus, Uninstall SDK and reboot Merlin and do a fresh install.

SQL Server Driver

Microsoft ODBC Driver < 17 is not compatible with Alkami SDK. If you are seeing any issues related Merlin failing SQL Server installation.

Double check you do not have < 17 installed. If so uninstall it and reboot Merlin and let Merlin install the correct drivers for you.

Picture shows the correct Version that SHOULD be installed.