Troubleshoot SQL Server on Linux
Applies to:
SQL Server - Linux
This article describes how to troubleshoot SQL Server running on Linux or in a Linux container. When troubleshooting SQL Server on Linux, remember to review the supported features and known limitations:
- Release notes for SQL Server 2022 on Linux
- Release notes for SQL Server 2019 on Linux
- Release notes for SQL Server 2017 on Linux
For answers to frequently asked questions, see the SQL Server on Linux FAQ.
Troubleshoot connection failures
If you have difficulty connecting to your Linux SQL Server instance, there are a few things to check.
If you're unable to connect locally using
localhost
, try using the IP address 127.0.0.1 instead. It's possible thatlocalhost
isn't properly mapped to this address.Verify that the server name or IP address is reachable from your client machine.
To find the IP address of your Ubuntu machine, you can run the
ifconfig
command as in the following example:sudo ifconfig eth0 | grep 'inet addr'
For Red Hat, you can use the
ip addr
command as in the following example:sudo ip addr show eth0 | grep "inet"
Tip
One exception to this technique relates to Azure VMs. For Azure VMs, find the public IP for the VM in the Azure portal.
If applicable, check that you opened the SQL Server port (default 1433) on the firewall.
For Azure VMs, check that you have a network security group rule for the default SQL Server port.
Verify that the user name and password don't contain any typos, extra spaces, or incorrect casing.
Try to explicitly set the protocol and port number with the server name like the following example:
tcp:servername,1433
.Network connectivity issues can also cause connection errors and timeouts. After verifying your connection information and network connectivity, try the connection again.
Manage the SQL Server service
The following section shows how to manage the execution of SQL Server Linux containers. To manage services for Linux, see Start, stop, and restart SQL Server services on Linux.
Manage the execution of the SQL Server Linux container
You can get the status and container ID of the latest created SQL Server Linux container by running the following command (The ID is under the CONTAINER ID
column):
sudo docker ps -l
You can stop or restart the SQL Server service as needed using the following commands:
sudo docker stop <container ID>
sudo docker restart <container ID>
Tip
For more troubleshooting tips for Linux containers, see Troubleshoot SQL Server Docker containers.
Access the log files
The SQL Server Database Engine logs to the /var/opt/mssql/log/errorlog
file in both the Linux and container installations. You need to be in superuser mode to browse this directory.
The installer logs here: /var/opt/mssql/setup-<time stamp representing time of install>
You can browse the errorlog
files with any UTF-16 compatible tool like vim or cat like this:
sudo cat errorlog
If you prefer, you can also convert the files to UTF-8 to read them with more or less with the following command:
sudo iconv -f UTF-16LE -t UTF-8 <errorlog> -o <output errorlog file>
Extended events
Extended events can be queried via a SQL command. For more information, see extended events.
Crash dumps
Look for dumps in the log directory in Linux. Check under the /var/opt/mssql/log
directory for Linux Core dumps (.tar.gz2
extension) or SQL minidumps (.mdmp
extension).
For example, to view core dumps:
sudo ls /var/opt/mssql/log | grep .tar.gz2
For SQL dumps, use this script:
sudo ls /var/opt/mssql/log | grep .mdmp
Start SQL Server in minimal configuration or in single user mode
Start SQL Server in minimal configuration mode
This mode is useful if the setting of a configuration value (for example, over-committing memory) prevents the server from starting.
sudo -u mssql /opt/mssql/bin/sqlservr -f
Start SQL Server in single user mode
Sometimes you might have to start an instance of SQL Server in single-user mode by using the startup option -m
. For more information, see startup parameters. For example, you might want to change server configuration options or recover a damaged master
database or other system database.
For example, use the following script to start SQL Server in single user mode:
sudo -u mssql /opt/mssql/bin/sqlservr -m
This script starts SQL Server in single user mode with sqlcmd:
sudo -u mssql /opt/mssql/bin/sqlservr -m sqlcmd
You should always start SQL Server on Linux with the mssql
user to prevent future startup issues. For example: sudo -u mssql /opt/mssql/bin/sqlservr [STARTUP OPTIONS]
If you accidentally start SQL Server with another user, you must change ownership of SQL Server database files back to the mssql
user before you start SQL Server with systemd. For example, to change ownership of all database files under /var/opt/mssql
to the mssql
user, run the following command:
chown -R mssql:mssql /var/opt/mssql/
Rebuild system databases
As a last resort, you can choose to rebuild the master
and model
databases back to default versions.
Warning
This process is dangerous, because you can delete all SQL Server system data that you have configured, including information about your user databases (but not the user databases themselves).
You need to attach the user databases to the instance afterwards. It also deletes other information stored in the system databases, including:
- database master key (DMK) information
- any certificates loaded in
master
- the password for the SA login
- job-related information from
msdb
- Database Mail information from
msdb
sp_configure
options
You aren't able to reattach any user databases encrypted with transparent data encryption (TDE) unless your certificates and private keys are also backed up.
Only use these steps if you understand the implications.
Stop SQL Server Database Engine
sudo systemctl stop mssql-server
Run sqlservr with the
force-setup
parametersudo -u mssql /opt/mssql/bin/sqlservr --force-setup
You should always start SQL Server on Linux with the
mssql
user to prevent future startup issues.After you see the message "Recovery is complete", press Ctrl+C. This shuts down SQL Server.
Reconfigure the SA password.
sudo /opt/mssql/bin/mssql-conf set-sa-password
Start SQL Server and reconfigure the server, including restoring or reattaching any user databases.
sudo systemctl start mssql-server
Improve performance
Many factors affect performance, including database design, hardware, and workload demands. If you're looking to improve performance, start by reviewing the best practices in the article, Performance best practices and configuration guidelines for SQL Server on Linux. Then explore some of the available tools for troubleshooting performance problems.
- Monitor performance by using the Query Store
- System dynamic management views
- Performance Dashboard in SQL Server Management Studio
Common issues
You can't connect to your remote SQL Server instance.
See the troubleshooting section of the article, Connect to SQL Server on Linux.
You experience the error message:
ERROR: Hostname must be 15 characters or less.
This is a known issue that happens whenever the name of the machine that is trying to install the SQL Server package is longer than 15 characters. There are currently no workarounds other than changing the name of the machine. You can do this by editing both
/etc/hostname
and/etc/hosts
, changing the hostname, saving each file, and restarting the computer.The system administration (SA) password must be reset, which stops the SQL Server service temporarily.
If you forget the system administrator (SA) password or need to reset it for some other reason, follow these steps.
Sign in to the host terminal, run the following commands and follow the prompts to reset the SA password:
sudo systemctl stop mssql-server sudo /opt/mssql/bin/mssql-conf setup
Special characters in login passwords cause errors or login failures.
If you use some characters in the SQL Server login password, you might need to escape them with a backslash when you use them on the Linux command line. For example, you must escape the dollar sign ($) anytime you use it in a terminal command/shell script:
Doesn't work:
sudo sqlcmd -S myserver -U sa -P Test$$
Does work:
sqlcmd -S myserver -U sa -P Test\$\$
Related content
Get help
- Ideas for SQL: Have suggestions for improving SQL Server?
- Microsoft Q & A (SQL Server)
- DBA Stack Exchange (tag sql-server): Ask SQL Server questions
- Stack Overflow (tag sql-server): Answers to SQL development questions
- Reddit: General discussion about SQL Server
- Microsoft SQL Server License Terms and Information
- Support options for business users
- Contact Microsoft
- Additional SQL Server help and feedback
Contribute to SQL documentation
Did you know that you can edit SQL content yourself? If you do so, not only do you help improve our documentation, but you also get credited as a contributor to the page.
For more information, see How to contribute to SQL Server documentation