Issue Overview: SQLiteConnection Constructor Throws ArgumentNullException in Single-File Deployments

The System.Data.SQLite.SQLiteConnection constructor throws a System.ArgumentNullException during initialization when deployed as a .NET 6/7 single-file executable. This occurs because the library attempts to resolve configuration or dependency paths using Assembly.Location, which returns an empty string in single-file bundles. The error manifests in the ConfigureViaOneFile method during a call to Path.Combine(), where one or more arguments become null due to invalid directory resolution.

The root conflict arises from the interaction between .NET’s single-file deployment model and the SQLite library’s assumptions about assembly locations. Single-file bundling merges managed assemblies into a monolithic executable, but native libraries like SQLite.Interop.dll remain external. The SQLite library attempts to locate configuration directories using Assembly.GetExecutingAssembly(), which fails because Assembly.Location is intentionally empty in single-file mode. This breaks path resolution logic in UnsafeNativeMethods.GetAssemblyDirectory(), leading to null arguments passed to Path.Combine().

The exception stack trace typically points to code attempting to construct a path like sds-see.eagle within a directory derived from the executing assembly’s location. Since the assembly’s location is empty, Path.Combine() receives invalid arguments. This issue is not exclusive to single-file bundles—it affects any scenario where assemblies are loaded from non-file-based sources (e.g., in-memory byte arrays or custom assembly load contexts).

Possible Causes: Assembly.Location Dependency and Single-File Deployment Constraints

Cause 1: Reliance on Assembly.Location for Native Library Resolution

The SQLite library uses Assembly.GetExecutingAssembly().Location in UnsafeNativeMethods.GetAssemblyDirectory() to determine the directory containing SQLite.Interop.dll. In single-file deployments, Assembly.Location returns an empty string, causing directory resolution to fail. This design violates .NET’s single-file deployment constraints, as documented in Microsoft’s warning IL3000, which explicitly states that Assembly.Location is empty for assemblies embedded in a single-file bundle.

Cause 2: Missing Fallback for Empty Configuration Directories

The ConfigureViaOneFile method does not account for scenarios where GetDirectory(DirectoryType.Configure) returns null or an empty string. When GetAssemblyDirectory() fails, the subsequent Path.Combine() call receives invalid arguments, triggering the ArgumentNullException. The absence of graceful degradation—such as falling back to AppContext.BaseDirectory or environment variables—exacerbates the issue.

Cause 3: Version-Specific Regressions in SQLite Library

Version 1.0.118.0 of System.Data.SQLite introduced a regression that exposed this issue, whereas earlier versions might have used alternative directory resolution strategies. Changes in native library loading logic or configuration file handling could have inadvertently removed safeguards against empty assembly locations.

Troubleshooting Steps, Solutions & Fixes: Resolving Path Resolution Failures in Single-File Contexts

Solution 1: Set SQLite_ConfigureDirectory Environment Variable

Override the default directory resolution by setting the SQLite_ConfigureDirectory environment variable to AppContext.BaseDirectory before initializing the SQLiteConnection:

Environment.SetEnvironmentVariable("SQLite_ConfigureDirectory", AppContext.BaseDirectory);  
var connection = new SQLiteConnection(connectionString);  

AppContext.BaseDirectory reliably returns the application’s base directory, even in single-file deployments. This forces the SQLite library to use a valid directory for configuration files and native library resolution.

Solution 2: Apply SQLite_NoConfigure Workaround

Disable the problematic configuration logic entirely by setting the SQLite_NoConfigure environment variable to "1":

Environment.SetEnvironmentVariable("SQLite_NoConfigure", "1");  
var connection = new SQLiteConnection(connectionString);  

This skips the ConfigureViaOneFile method, avoiding the call to Path.Combine() that triggers the exception. Use this workaround if configuration files like sds-see.eagle are unnecessary for your application.

Solution 3: Upgrade to System.Data.SQLite 1.0.119.0 or Later

Version 1.0.119.0 includes a fix for this issue. Update the NuGet package or DLL reference to this version:

dotnet add package System.Data.SQLite --version 1.0.119  

The updated library handles single-file deployments more gracefully, either by using AppContext.BaseDirectory internally or bypassing the faulty path resolution logic.

Solution 4: Modify Native Library Loading for Custom Assembly Contexts

For advanced scenarios involving in-memory assembly loading or custom AssemblyLoadContext, explicitly specify the native library directory. Override the native library resolution logic using SQLiteFunction.SetLoadProxy() or a custom DllImportResolver:

NativeLibrary.SetDllImportResolver(typeof(SQLiteConnection).Assembly, (name, assembly, path) =>  
{  
    string nativeLibPath = Path.Combine(AppContext.BaseDirectory, "SQLite.Interop.dll");  
    return NativeLibrary.Load(nativeLibPath);  
});  

This redirects the SQLite library to load SQLite.Interop.dll from the application’s base directory, bypassing assembly-location-based resolution.

Solution 5: Adjust Single-File Deployment Settings

Modify the .NET publish profile to include SQLite.Interop.dll as a separate file, even in single-file mode. Add the following to your .csproj file:

<ItemGroup>  
  <Content Include="path\to\SQLite.Interop.dll">  
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>  
    <Link>%(Filename)%(Extension)</Link>  
    <PublishState>Included</PublishState>  
    <Visible>false</Visible>  
  </Content>  
</ItemGroup>  

This ensures the native library is copied to the output directory, allowing the SQLite library to locate it without relying on Assembly.Location.

Solution 6: Patch System.Data.SQLite via Reflection

If upgrading is not feasible, use reflection to modify the SQLite library’s directory resolution logic at runtime:

var field = typeof(System.Data.SQLite.UnsafeNativeMethods)  
    .GetField("_assemblyDirectory", BindingFlags.NonPublic | BindingFlags.Static);  
field.SetValue(null, AppContext.BaseDirectory);  

This directly sets the internal _assemblyDirectory field to a valid path, circumventing the faulty GetAssemblyDirectory() method.

Solution 7: Use NativeAOT-Compatible Deployment

If targeting .NET 7 or later, consider using NativeAOT compilation with explicit native library bundling. Configure the project to include SQLite.Interop.dll as a native resource:

<ItemGroup>  
  <NativeLibrary Include="SQLite.Interop.dll" />  
</ItemGroup>  

NativeAOT deployments handle native libraries more predictably, reducing reliance on runtime path resolution.

Solution 8: Validate Deployment Artifacts

After publishing, verify that SQLite.Interop.dll exists in the output directory alongside the single-file executable. Use a post-build script to ensure the file is not excluded during deployment:

dotnet publish -c Release -r win-x64 --self-contained true /p:PublishSingleFile=true  
cp SQLite.Interop.dll ./bin/Release/net7.0/win-x64/publish/  

Manual inclusion guarantees the library can locate its dependencies.

Solution 9: Implement a Custom AssemblyLoadContext

For applications loading assemblies from byte arrays or dynamic sources, create a custom AssemblyLoadContext that overrides LoadUnmanagedDll():

public class CustomLoadContext : AssemblyLoadContext  
{  
    protected override IntPtr LoadUnmanagedDll(string unmanagedDllName)  
    {  
        string path = Path.Combine(AppContext.BaseDirectory, unmanagedDllName);  
        return LoadUnmanagedDllFromPath(path);  
    }  
}  

Use this context to load the SQLite assembly, ensuring unmanaged DLLs are resolved from the correct directory.

Solution 10: File a Feature Request for Official Single-File Support

While System.Data.SQLite does not officially support single-file deployments, community feedback can prioritize this issue. Submit a request to the project’s issue tracker, referencing the IL3000 warning and the need for AppContext.BaseDirectory fallbacks.

By systematically addressing the root cause—invalid directory resolution in single-file contexts—these solutions restore SQLite functionality across deployment scenarios.