Here are some common Integration Runtime (IR) registration errors you might encounter when setting up a Self-hosted Integration Runtime (SHIR) in Azure Data Factory, along with their types and potential resolutions:
Summary of the Self-hosted Integration Runtime (IR) registration errors and their resolutions in a tabular form:
| Error Type | Description | Resolution |
|---|---|---|
| Authentication Failed | Invalid or expired authentication key. | Regenerate the key from Azure Data Factory and use the new key to re-register the IR. |
| Network Connectivity Error | Unable to connect to Azure Data Factory service. | Ensure internet access, open ports 443/1688, configure proxy settings, and check DNS resolution. |
| Permission Denied | User lacks necessary permissions. | Assign the user Contributor or higher role in Azure Data Factory resource’s IAM settings. |
| Integration Runtime Already Registered | IR is already registered on another machine. | Unregister IR from the old machine or restart the IR service and attempt to re-register. |
| Integration Runtime is Offline | IR is not reachable from Azure Data Factory. | Restart the Self-hosted IR service on the machine and ensure network connectivity. |
| Outbound Communication Error | Cannot connect to Azure service endpoints. | Open outbound access on port 443 for Azure service URLs or whitelist Azure Data Factory IPs in the firewall. |
| Proxy Authentication Error | Proxy authentication failed during registration. | Configure proxy settings in the Self-hosted IR Configuration Manager with correct credentials. |
| SSL/TLS Certificate Error | SSL certificate validation failed. | Ensure correct system time, trust the certificate authority, and validate MITM proxy configurations. |
| Outdated Version Error | IR version is outdated and incompatible with ADF. | Download and install the latest version of Self-hosted IR from the Azure portal and restart the service. |
| Operating System Not Supported | The OS version is not supported for IR installation. | Use a machine with a 64-bit Windows 10 or Windows Server 2016 (or later) and ensure it meets system requirements. |
1. Authentication Failed Error
Error Type: Authentication Key is Invalid
This occurs if the authentication key used during registration is invalid or expired.
Resolution:
- Go to Azure Data Factory > Manage > Integration Runtimes.
- Click on your Self-hosted IR and select Regenerate Key.
- Use the new authentication key to re-register the IR on your machine.
2. Network Connectivity Error
Error Type: Unable to Connect to the Azure Data Factory Service
This happens when the Self-hosted IR cannot connect to the Azure Data Factory service due to network issues (e.g., firewall, proxy, or DNS problems).
Resolution:
- Check Internet Access: Ensure the machine hosting the IR has stable internet access.
- Firewall Settings: Ensure outbound access on ports 443 (HTTPS) and 1688 (for licensing) is allowed.
- Proxy Configuration: If your network uses a proxy, ensure the proxy settings are configured correctly during the IR installation. You can specify these settings using the IR configuration tool.
- DNS Issues: Ensure the DNS is properly resolving Azure URLs such as
*.datafactory.azure.net.
3. Permission Denied Error
Error Type: User Lacks Required Permissions
Occurs if the user trying to register the Self-hosted IR doesn’t have proper permissions in Azure Data Factory.
Resolution:
- Ensure that the user has been assigned the Contributor role or higher on the Azure Data Factory resource.
- Go to the Azure portal > Resource Group and check the IAM (Identity and Access Management) permissions. Add the user under Access control (IAM) if needed.
4. Self-hosted Integration Runtime is Already Registered
Error Type: The Integration Runtime has already been registered
Occurs when you try to register an IR that has already been registered on a different machine or during a previous attempt.
Resolution:
- Check the Machine: If you need to move the IR to a new machine, you’ll have to first unregister it from the old machine using the Self-hosted Integration Runtime Configuration Manager.
- Re-register: If the machine is the correct one but you still see the error, restart the IR service from the Windows Services manager and try registering again.
5. Integration Runtime is Offline
Error Type: Integration Runtime is not online
This error occurs when the IR was previously registered but is not currently reachable by Azure Data Factory (ADF).
Resolution:
- Check the Service Status: Go to the machine where the IR is installed and open the Self-hosted Integration Runtime Configuration Manager. Ensure the status shows as Running.
- Restart the IR Service: If the status is not running, restart the Self-hosted Integration Runtime service from Windows Services.
- Check Network Connectivity: Ensure the machine has proper internet connectivity. Test if the IR can connect to Azure endpoints.
6. Outbound Communication Error
Error Type: Cannot connect to Azure Service Endpoints
Occurs when the IR machine is unable to reach Azure endpoints due to firewall or network restrictions.
Resolution:
- Ensure outbound communication is allowed on port 443 (HTTPS) for the following URLs:
*.servicebus.windows.net*.datafactory.azure.net*.frontend.clouddatahub.net
- If using a proxy, ensure the proxy settings are correct and the IR is configured to work with the proxy.
- Whitelist Azure Data Factory IPs: Ensure the IP addresses used by Azure Data Factory in your region are whitelisted in your firewall.
7. Proxy Authentication Error
Error Type: Proxy Authentication Failed
This happens if the IR is behind a corporate proxy that requires authentication, and the credentials are either missing or incorrect.
Resolution:
- During the installation or through the Self-hosted Integration Runtime Configuration Manager, go to the Proxy Settings tab.
- Enter the correct proxy server address, port, username, and password.
- Ensure that your proxy server is allowing the necessary connections to the Azure service endpoints.
8. SSL/TLS Certificate Error
Error Type: SSL Certificate Could Not Be Validated
Occurs when the machine hosting the IR cannot validate the SSL certificate from the Azure Data Factory service.
Resolution:
- Ensure that the machine’s system time is correct, as SSL certificates rely on correct timestamps.
- Verify that your machine trusts the certificate authority (CA) issuing the SSL certificates for Azure services.
- If using a corporate network, ensure that any man-in-the-middle (MITM) proxy servers are properly configured to trust Azure services.
9. Outdated Version Error
Error Type: Self-hosted Integration Runtime Version is Outdated
This occurs when the version of the Self-hosted IR on your machine is outdated and incompatible with Azure Data Factory.
Resolution:
- Download and install the latest version of the Self-hosted Integration Runtime from the Azure Data Factory Integration Runtime setup page.
- Restart the service after updating to ensure it runs the latest version.
10. Operating System Not Supported
Error Type: Unsupported OS Version
Occurs when attempting to install Self-hosted IR on an unsupported operating system or environment (e.g., an old version of Windows).
Resolution:
- Ensure the machine meets the minimum requirements:
- Windows 64-bit version (Windows 10, Windows Server 2016, or later).
- The machine should have at least 4GB of RAM and sufficient CPU resources.
- Update your OS if necessary, or use a different machine that meets the requirements.
General Troubleshooting Steps:
- Check Logs: Open the Self-hosted Integration Runtime Configuration Manager and look at the logs for more detailed error messages.
- Restart the Service: Sometimes, simply restarting the Integration Runtime service on the machine can resolve minor errors.
- Verify System Requirements: Ensure that the machine hosting the IR has sufficient resources (RAM, CPU, etc.) and is running a supported operating system.
- Update the IR: Ensure that you are running the latest version of the Integration Runtime. You can find updates on the Microsoft download page.
