SQL Server Agent on Linux Not Starting? Try This 10-Step Troubleshooting Guide

The SQL Server Agent service on Linux is a powerful tool for automating and scheduling administrative tasks, including the execution of Transact-SQL scripts, Integration Services packages, or Analysis Services commands.

However, there are times when the SQL Server Agent service fails to start, hindering or disrupting your workflows. This comprehensive guide will walk you through various steps to diagnose and resolve hostname-related issues, system logs, and other possible causes that might prevent the SQL Server Agent service on Linux from starting.

1. Checking the Hostname

When troubleshooting the SQL Server Agent service not starting, you should first check that your Linux machine’s hostname meets the 15-character maximum limitation. You can use the hostnamectl command to check the current hostname.

1.1. Using the Hostnamectl Command

To check the hostname of your Linux machine, open a terminal window and type the following command:

hostnamectl

This will display the current hostname, along with additional system information. Ensure that the hostname does not exceed the 15-character limit and exceed the maximum limit.

If your hostname is longer than 15 characters, you can change it by running the following command:

sudo hostnamectl set-hostname <NewHostname>

Replace <NewHostname> with a suitable hostname under the character limit.

2. Verifying the /etc/hosts File

The SQL Server Agent service on Linux requires the system to have the correct hostname configured in the /etc/hosts file. This file maps hostnames to IP addresses, essential for proper communication between the SQL Server Agent and other services.

2.1. Checking the /etc/hosts File

To check the /etc/hosts file, open a terminal window and type the following command:

cat /etc/hosts

Ensure that the /etc/hosts file has an entry for the hostname that resolves to the machine’s IP address. If the entry is missing or incorrect, edit the file using a text editor and add the appropriate entry.

2.2. Editing the /etc/hosts File

To edit the /etc/hosts file, open a terminal window and type the following command:

sudo nano /etc/hosts

This will open the file in the Nano text editor. Add or modify the entry for your hostname and IP address, then save the changes by pressing Ctrl + X, followed by Y and Enter.

3. Restarting the SQL Server Agent Service

After ensuring that the hostname and /etc/hosts file are configured correctly, try restarting the SQL Server Agent service by running the following command as root:

sudo systemctl restart mssql-server-agent

This will attempt to restart the SQL Server Agent service, which may resolve the issue if caused by a temporary problem or misconfiguration.

4. Checking the System Logs

If the SQL Server Agent service still fails to start, it’s essential to examine the system logs for any errors related to the service. You can use the journalctl command to view the system logs.

4.1. Viewing System Logs with Journalctl

To view the system logs, open a terminal window and type the following command:

sudo journalctl -u mssql-server-agent

This will display the logs for the SQL Server Agent service, which may contain information about the errors or issues preventing the service from starting.

5. Checking the SQL Server Agent Logs

In addition to the system logs, the SQL Server Agent logs may contain errors or warnings preventing the service from starting. These logs are in the /var/opt/mssql/log directory.

5.1. Viewing the SQL Server Agent Logs

To view the SQL Server Agent logs, open a terminal window and type the following command:

sudo cat /var/opt/mssql/log/SQLAgent.out

This will display the SQL Server Agent log file, which may contain helpful information about the issues causing the service to fail.

6. Verifying the SQL Server Agent Configuration

An incorrect configuration is another possible cause for the SQL Server Agent service not starting on Linux. You can check the SQL Server Agent configuration by running the following command as a SQL Server administrator:

EXEC sp_configure 'show advanced options', 1;
RECONFIGURE WITH OVERRIDE;
EXEC sp_configure 'Agent XPs', 1;
RECONFIGURE WITH OVERRIDE;

This command will ensure that the SQL Server Agent is enabled and the necessary configurations are set.

7. Ensuring Required Permissions

The SQL Server Agent service on Linux requires specific permissions to access the necessary files and directories. Ensure that the MySQL user has the required permissions by running the following command:

sudo chown -R mssql:mssql /var/opt/mssql

This command will set the ownership of the /var/opt/mssql directory and its contents to the MySQL user and group.

8. Checking Firewall and Network Configuration

The SQL Server Agent service on Linux communicates with other services and components over the network. If the service is not starting, it could be due to a misconfigured firewall or network settings.

8.1. Checking Firewall Rules

To check if the firewall is blocking the SQL Server Agent service, run the following command:

sudo firewall-cmd --list-all

This command will display the current firewall rules, which should allow the necessary ports for the SQL Server Agent service to operate.

8.2. Modifying Firewall Rules

If the firewall rules are blocking the SQL Server Agent service, you can add the necessary rules by running the following commands:

sudo firewall-cmd --permanent --add-port=1433/tcp sudo firewall-cmd --permanent --add-port=1434/tcp sudo firewall-cmd --reload

These commands will add the required ports to the firewall and reload the firewall configuration.

9. Updating SQL Server

If the SQL Server Agent service on Linux fails to start after trying the previous steps, it could be due to a known issue that was fixed in a later update. Ensure that your SQL Server installation is up-to-date by running the following command:

sudo yum update mssql-server

This command will update your SQL Server installation to the latest version, which may resolve the issue with the SQL Server Agent service not starting.

10. Seeking Further Assistance

In conclusion, troubleshooting the SQL Server Agent service on Linux not starting can be a complex task. This guide has provided a basic approach to diagnosing and resolving hostname-related issues, system logs, and other possible causes. By following these steps, you should be able to identify and fix the problem, ensuring the smooth operation of your SQL Server Agent service on Linux.

If you still need assistance with your SQL Server workload, we can help. 

 Ref. https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-troubleshooting-guide?view=sql-server-ver15#bkmk_agentservice