LykosAI/StabilityMatrix · critical · FileNotFoundException

Python linked library not found

Error message

Python linked library not found

What it means

PyRunner.InitializeWithInstallation configures the embedded Python runtime (Python.NET) with the installation's DLL before calling PythonEngine.Initialize(). If the Python DLL (e.g. python310.dll) is missing at installation.PythonDllPath, a FileNotFoundException carrying the DLL path is thrown, because initializing without the DLL would crash or fail obscurely.

Solutions

  1. Re-download/reinstall the shared Python runtime via the installation manager
  2. Verify installation.PythonDllPath points to an existing file; fix the installation record if stale
  3. Check antivirus quarantine for the python DLL and whitelist the folder
  4. Recreate the environment or re-point the app's data directory to the correct install

Example fix

// before
if (!File.Exists(installation.PythonDllPath)) throw ... // dll missing
// after
if (!File.Exists(installation.PythonDllPath))
{
    await installationManager.ReinstallSharedRuntimeAsync(installation.Version);
}
await pyRunner.Initialize(installation);
Defensive patterns

Strategy: validation

Validate before calling

if (!File.Exists(installation.PythonDllPath))
    throw new InvalidOperationException($"Python DLL missing: {installation.PythonDllPath}");

Try / catch

try
{
    await pyRunner.Initialize();
}
catch (FileNotFoundException ex)
{
    logger.LogError(ex, "Python DLL missing; reinstalling shared runtime");
    await installationManager.ReinstallSharedRuntimeAsync();
    await pyRunner.Initialize();
}

Prevention

When it happens

Trigger: Initializing the Python runtime when the installation's PythonDllPath file does not exist — incomplete/corrupted install, path misconfigured in the installation record, or the DLL was deleted/AV-quarantined.

Common situations: Interrupted Python runtime download, antivirus removing python dll, moving the app data folder without reconfiguring paths, broken installation metadata pointing at a stale path.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of LykosAI/StabilityMatrix@af93d6ef57 (2026-09-12). Data as JSON: /api/errors/659837b9a3220280. Report an issue: GitHub.

Appendix: source

Thrown at StabilityMatrix.Core/Python/PyRunner.cs:200

    /// Initialize Python runtime with a specific installation
    /// </summary>
    private async Task InitializeWithInstallation(PyInstallation installation)
    {
        if (PythonEngine.IsInitialized)
            return;

        Logger.Info("Setting PYTHONHOME={PythonDir}", installation.InstallPath.ToRepr());

        // Append Python path to PATH
        var newEnvPath = Compat.GetEnvPathWithExtensions(installation.InstallPath);
        Logger.Debug("Setting PATH={NewEnvPath}", newEnvPath.ToRepr());
        Environment.SetEnvironmentVariable("PATH", newEnvPath, EnvironmentVariableTarget.Process);

        Logger.Info("Initializing Python runtime with DLL: {DllPath}", installation.PythonDllPath);
        // Check PythonDLL exists
        if (!File.Exists(installation.PythonDllPath))
        {
            throw new FileNotFoundException("Python linked library not found", installation.PythonDllPath);
        }

        Runtime.PythonDLL = installation.PythonDllPath;
        PythonEngine.PythonHome = installation.InstallPath;
        PythonEngine.Initialize();
        PythonEngine.BeginAllowThreads();

        // Redirect stdout and stderr
        StdOutStream = new PyIOStream();
        StdErrStream = new PyIOStream();
        await RunInThreadWithLock(() =>
            {
                var sys =
                    Py.Import("sys") as PyModule ?? throw new NullReferenceException("sys module not found");
                sys.Set("stdout", StdOutStream);
                sys.Set("stderr", StdErrStream);
            })
            .ConfigureAwait(false);

View on GitHub (pinned to af93d6ef57)