Top Issues - microsoft/SqlNexus GitHub Wiki

Issues related to running SQL Nexus

1. File Blocked after download

When downloading SQL Nexus from the internet, Windows may block the executable.

  • Right-click sqlnexus.exe and select Properties
  • If the file is blocked you will see an Unblock checkbox or button at the bottom — check it and click OK

2. "Windows Protected your PC" SmartScreen warning

When running SQL Nexus for the first time on Windows 10/11 you may see a SmartScreen warning.

  • Click More Info and then select Run Anyway

3. ReadTrace (RML Utilities) not found or import produces no trace results

SQL Nexus requires RML Utilities (ReadTrace.exe) version 9.3.78 or later to import .trc and .xel trace files.

  • Download the latest RML Utilities from the RML Utility page
  • If ReadTrace is not found, the ReadTrace importer will be disabled by default in the Import Options
  • Verify ReadTrace.exe is installed in the same directory as sqlnexus.exe or in a path SQL Nexus can discover

4. "Database already contains Nexus data" message at import

If you attempt to import into a database that was previously used with SQL Nexus, you will see this message.

  • In the Import window click Options and check Drop existing tables before importing, or
  • Select <New Database> from the database dropdown on the toolbar to import into a fresh database

5. Reports show no data after import

This typically happens when:

  • Wrong data path: Ensure you provide the folder path where collected data resides, not an individual file name
  • Multiple SQL instances in data: If data was collected from a machine with multiple SQL Server instances, SQL Nexus will prompt you to select which instance to import — make sure you select the correct one
  • ReadTrace importer was disabled: Check Import → Options → Importers and verify the ReadTrace importer is enabled if you expect trace-based reports (Bottleneck Analysis, Top Queries, etc.)
  • No matching files found: Verify the collection folder contains files matching the expected patterns (.out, .trc, .xel, .blg)

6. SQL Nexus requires a non-production SQL Server instance

SQL Nexus imports diagnostic data into a SQL Server database and runs analysis scripts against it.
Do not point SQL Nexus at a production SQL Server instance. Use a dedicated developer or test instance.
SQL Server 2016 or later is required.

7. .NET Framework 4.8 is required

If SQL Nexus fails to launch, ensure .NET Framework 4.8 is installed on the machine.

8. Linux performance data not importing

Linux perf data (IO stats, CPU, memory, networking) collected via SQL LogScout requires the Linux Perf Importer to be enabled.

  • In the Import window click Options → Importers and verify Linux Perf is enabled
  • The option "Import to SQL (Linux Perf)" must be checked for data to be loaded into the database

9. XEL files (SQLDiag, Always On Health, System Health) not imported

These three XEL file types are disabled by default to avoid inflating database size.

  • In the Import window click Options → Importers and enable the desired XEL import options before running the import
  • See Detailed XEvents Tracing for more details