pyinstaller builds - <built-in function connect> returned NULL without setting an exception

[BotBlake]

Description

This issue is simmilar to the closed issues #294 and #886!
Since both of them do not contain any solution for this, I am opening a new one.

Using ibm_db normaly works fine. Bundling it in a pyinstaller .exe-build, it throws the following Error:
<built-in function connect> returned NULL without setting an exception

Steps to Reproduce:

1. use ibm_db.connect(database, username, password) somewhere in your script (script.py)
2. bundle script into .exe-File via pyinstaller ./script.py
3. run script.exe -> Observe Error

Sadly, even when attaching additional debug statements to the script, this is the only Error message I am abled to find.
On one of the other two issues, I saw someone asking for the output of db2trc from reproducing this error - I have attached the trc.flw below.

Test Scripts

main.py - just connecting to the Database.

import creds # Local file containing password, username and database-name
import os, logging, locale, traceback

locale.setlocale(locale.LC_ALL, "de_de")
logging.basicConfig(level=logging.DEBUG)

dll_path = r"C:\Program Files\IBM\SQLLIB_RTC_115\BIN"
os.add_dll_directory(dll_path)
import ibm_db

print(f"Testing DLL Folder {os.path.exists(dll_path)}")

try:
    print("Normal Connect")
    db_connection = ibm_db.connect(creds.database, creds.username, creds.password)
    print("Connected...")
    print(f"1: {ibm_db.conn_error(db_connection)}")
    print(f"2: {ibm_db.conn_errormsg(db_connection)}")
except Exception as e:
    traceback.print_exc()
    traceback.print_exception(e)
    print(e)

-> running main.py directly works fine.

build.py

import subprocess

pyinstaller_command = [
        "pyinstaller", "--onefile",
        "--name", "test",
        "./main.py",
        "--console", "--debug", "all"
    ]

subprocess.run(pyinstaller_command)

Running test.exe (in a shell, even with admin) outputs:
<built-in function connect> returned NULL without setting an exception
Whilst I am running pyinstaller in --onefile mode, the error also reproduces just fine without!

Environment

• Operating System Name: Windows
• db2level output from clidriver if in use:

DB21085I  This instance or install (instance name, where applicable: "DB2")
uses "64" bits and DB2 code release "SQL11059" with level identifier
"060A010F".
Informational tokens are "DB2 v11.5.9000.352", "s2310270807",
"DYN2310270807WIN64", and Fix Pack "0".
Product is installed at "C:\PROGRA~1\IBM\SQLLIB~1" with DB2 Copy Name
"DB2_RTC_115".

• Target Db2 Server Version: DB2 z/OS 13.1.7
• Python Version: 3.13.7
• ibm_db version: 3.2.8
• Value of below environment variables if set:
  None (see code example)

Additional

logging the trace output of the db2 clidriver, you get the following information:

<db2trc_header>
Marker                  :  @TRACE@
Trace version           :      7.0
Platform                : NT 64BIT
Build level             : s2310270807
maxBufferSize           : 2097152 bytes (2 MB)
auxBufferSize           : 0 bytes (0 MB)
allocationCount         : 0
DB2TRCD pid             : 1
Trace destination       : trc.dmp
numSuspended            : 0
Trace starting time     : 2025-12-11-09.58.57.212000+060
Trace status            : UNKNOWN
Trace status change time: N/A
Buffer size             : 2097152 bytes (2 MB)
Allow buffer to wrap    : yes
Mask                    : *.*.*.*.*
Timestamps              : disabled
PID.TID mask            : all
Fixed data mask #1      : all
Fixed data mask #2      : all
Max system errors       : infinite
Treat this rc as sys err: none
sqlcodes for stoptrc    :  none
Search Pattern          : none
clitracelevel           : none
Member mask             : none
Application handle mask : none
Application ID mask     : none

</db2trc_header>

pid = 4720 tid = 4724 node = 0

1           sqloMgmtServiceCtrlHandler entry
2           | ReportServiceStatus_DB2MGMTSVC entry
3           | ReportServiceStatus_DB2MGMTSVC exit [rc = 1]
4           sqloMgmtServiceCtrlHandler exit
5           sqloMgmtServiceCtrlHandler entry
6           | ReportServiceStatus_DB2MGMTSVC entry
7           | ReportServiceStatus_DB2MGMTSVC exit [rc = 1]
8           sqloMgmtServiceCtrlHandler exit

[BotBlake]

I was thinking that I have seen this working before, so I tested with a super old python version. (Downgrading to that is not an option for me due to various reasons)

On ibm_db version 2.0.7 combined with Python 3.4.3 this works!
I needed to modify main and build scripts, they now look like so (and again, are functional!)

main.py

import creds
import os, logging, traceback

logging.basicConfig(level=logging.DEBUG)
import ibm_db

try:
    print("Normal Connect", flush=False)
    db_connection = ibm_db.connect(creds.database, creds.username, creds.password)
    print("Connected...", flush=False)
    print("1: "+ibm_db.conn_error(db_connection), flush=False)
    print("2: "+ibm_db.conn_errormsg(db_connection), flush=False)
except Exception as e:
    traceback.print_exc()
    print(e, flush=False)

build.py

from PyInstaller.__main__ import run

raw_command = [
    "--onefile",
    "--name", "oldpython",
    "./main.py"
]

run(raw_command)

How can that be?

[Earammak]

@BotBlake ,I tried to run in my system, it's working fine for me with .exe file.
If you are still facing the issue, please share with how you created .exe file, pyinstaller installed path.

Thanks

[BotBlake]

Hi there @Earammak,
yes, I am still facing this issue!

Have you already tried using the build script I provided above?
For me, the issue occurs with Python 3.13 and ibm_db 3.2.8, but NOT with Python 3.4 and ibm_db 2.0.7.

My .exe file is built from the provided main.py using build.py.
If it works for you in .exe builds, would you mind sharing your build-script for me to test?

Kind regards

[Earammak]

@BotBlake I tested this using the same build.py script and the build works fine in my environment — the executable runs and connects successfully.
I executed on python 3.12 for python-ibmdb 3.2.8.

Here is the executed output for your shared script:
oldpython.exe
Testing DLL Folder True
Normal Connect
Connected...
1:
2:

I don't think we can share .exe file here, as it uses our connection string for connecting to the database.

Thanks

[BotBlake]

@Earammak
Perhaps the issue is with python 3.13 then?
I am unabled to test with python 3.12 on the production deployment myself.

That is the only difference between our setupts afaik.
Or do you have any environment variables set that would make a difference?
Thanks and kind regards!

[Earammak]

@BotBlake I’ve tested this with Python 3.13 and can confirm the build and connection work fine in my environment.
You set clidriver/dsdriver PATH in your environment?

[BotBlake]

Hi @Earammak
No, I did not set any system variables specific to this library.
Would that be needed for .exe binaries? - I need to ship the Application as is, which is why I am setting the DLL Path Variable during runtime:

dll_path = r"C:\Program Files\IBM\SQLLIB_RTC_115\BIN"
os.add_dll_directory(dll_path)

[Earammak]

@BotBlake ,
Here is the below steps followed.
Scripts are same as yours.
C:\Users\ek\OneDrive\Python_work>python build1.py
499 INFO: PyInstaller: 6.19.0, contrib hooks: 2026.2
500 INFO: Python: 3.13.0
613 INFO: Platform: Windows-11-10.0.26100-SP0
613 INFO: Python environment: C:\Program Files\Python313
619 INFO: wrote C:\Users\ek\OneDrive\Python_work\test.spec
643 INFO: Module search paths (PYTHONPATH):
['C:\Program Files\Python313\Scripts\pyinstaller.exe',
'C:\Program Files\Python313\python313.zip',
'C:\Program Files\Python313\DLLs',
'C:\Program Files\Python313\Lib',
'C:\Program Files\Python313',
'C:\Program Files\Python313\Lib\site-packages',
'C:\Users\ek\OneDrive\Python_work']
1665 INFO: checking Analysis
1669 INFO: Building because hookspath changed
1669 INFO: Looking for Python shared library...
1669 INFO: Using Python shared library: C:\Program Files\Python313\python313.dll
1669 INFO: Running Analysis Analysis-00.toc
1669 INFO: Target bytecode optimization level: 0
1669 INFO: Initializing module dependency graph...
1672 INFO: Initializing module graph hook caches...
1724 INFO: Analyzing modules for base_library.zip ...
5431 INFO: Processing standard module hook 'hook-encodings.py' from 'C:\Program Files\Python313\Lib\site-packages\PyInstaller\hooks'
8424 INFO: Processing standard module hook 'hook-pickle.py' from 'C:\Program Files\Python313\Lib\site-packages\PyInstaller\hooks'
10206 INFO: Processing standard module hook 'hook-heapq.py' from 'C:\Program Files\Python313\Lib\site-packages\PyInstaller\hooks'
11149 INFO: Caching module dependency graph...
11201 INFO: Analyzing C:\Users\ek\OneDrive\Python_work\main.py
11209 INFO: Processing module hooks (post-graph stage)...
11216 INFO: Performing binary vs. data reclassification (1 entries)
11220 INFO: Looking for ctypes DLLs
11227 INFO: Analyzing run-time hooks ...
11231 INFO: Including run-time hook 'pyi_rth_inspect.py' from 'C:\Program Files\Python313\Lib\site-packages\PyInstaller\hooks\rthooks'
11242 INFO: Creating base_library.zip...
11285 INFO: Looking for dynamic libraries
11768 INFO: Extra DLL search directories (AddDllDirectory): []
11768 INFO: Extra DLL search directories (PATH): []
11976 WARNING: Library not found: could not resolve 'DB2CLI64.dll', dependency of 'C:\Program Files\Python313\Lib\site-packages\ibm_db.cp313-win_amd64.pyd'.
11997 INFO: Warnings written to C:\Users\ek\OneDrive\Python_work\build\test\warn-test.txt
12021 INFO: Graph cross-reference written to C:\Users\ek\OneDrive\Python_work\build\test\xref-test.html
12069 INFO: checking PYZ
12071 INFO: Building because toc changed
12071 INFO: Building PYZ (ZlibArchive) C:\Users\ek\OneDrive\Python_work\build\test\PYZ-00.pyz
12319 INFO: Building PYZ (ZlibArchive) C:\Users\ek\OneDrive\Python_work\build\test\PYZ-00.pyz completed successfully.
12324 INFO: checking PKG
12325 INFO: Building because toc changed
12326 INFO: Building PKG (CArchive) test.pkg
13673 INFO: Building PKG (CArchive) test.pkg completed successfully.
13676 INFO: Bootloader C:\Program Files\Python313\Lib\site-packages\PyInstaller\bootloader\Windows-64bit-intel\run.exe
13676 INFO: checking EXE
13678 INFO: Building because icon changed
13678 INFO: Building EXE from EXE-00.toc
13679 INFO: Copying bootloader EXE to C:\Users\ek\OneDrive\Python_work\dist\test.exe
13701 INFO: Copying icon to EXE
13713 INFO: Copying 0 resources to EXE
13713 INFO: Embedding manifest in EXE
13724 INFO: Appending PKG archive to EXE
13743 INFO: Fixing EXE headers
14578 INFO: Building EXE from EXE-00.toc completed successfully.
14580 INFO: Build complete! The results are available in: C:\Users\ek\OneDrive\Python_work\dist

C:\Users\ek\OneDrive\Python_work>
C:\Users\ek\OneDrive\Python_work\dist>test.exe
Testing DLL Folder True
Normal Connect
Connected...
1:
2:

This is how i executed.

Thanks,

[Earammak]

@BotBlake , Can you please share the update ?

Thanks

[Earammak]

@BotBlake , Since there have been no further updates, I’ll close this issue for now.
If you still face the issue, please feel free to reopen it again.

Thanks

[BotBlake]

Hi there @Earammak
Yes, I am still facing this issue.

If you still face the issue, please feel free to reopen it again.

I lack the permission to re-open issues on this Repo so I cannot do that.

Since opening this issue have updated both ìbm_db (3.2.9) and pyinstaller (6.20.0).
Other then that, the setup remained the same. No environment variables for the IBM driver are set at all on the system!

Running the Test Script manually works fine for me.
The output is:

main.py 
Normal Connect
Connected...
1: 
2: 

When I package it using the Build script, the following happens:

python build.py
353 INFO: PyInstaller: 6.20.0, contrib hooks: 2026.4
354 INFO: Python: 3.13.7
505 INFO: Platform: Windows-11-10.0.26100-SP0
505 INFO: Python environment: C:\Users\botblake\Documents\prod_companion\.venv
507 INFO: wrote C:\Users\botblake\Documents\test_stuff\oldpython.spec
515 INFO: Module search paths (PYTHONPATH):
['C:\\Users\\botblake\\Documents\\test_stuff',
 'C:\\Users\\botblake\\Documents\\WinPython-64bit-3.13.7\\python313.zip',
 'C:\\Users\\botblake\\Documents\\WinPython-64bit-3.13.7\\DLLs',
 'C:\\Users\\botblake\\Documents\\WinPython-64bit-3.13.7\\Lib',
 'C:\\Users\\botblake\\Documents\\WinPython-64bit-3.13.7',
 'C:\\Users\\botblake\\Documents\\test_stuff\\.venv',
 'C:\\Users\\botblake\\Documents\\test_stuff\\.venv\\Lib\\site-packages',
 'C:\\Users\\botblake\\Documents\\test_stuff']
1775 INFO: checking Analysis
1775 INFO: Building Analysis because Analysis-00.toc is non existent
1776 INFO: Looking for Python shared library...
1776 INFO: Using Python shared library: C:\Users\botblake\Documents\WinPython-64bit-3.13.7\python313.dll
1776 INFO: Running Analysis Analysis-00.toc
1776 INFO: Target bytecode optimization level: 0
1776 INFO: Initializing module dependency graph...
1779 INFO: Initializing module graph hook caches...
1823 INFO: Analyzing modules for base_library.zip ...
6100 INFO: Processing standard module hook 'hook-heapq.py' from 'C:\\Users\\botblake\\Documents\\test_stuff\\.venv\\Lib\\site-packages\\PyInstaller\\hooks'
6335 INFO: Processing standard module hook 'hook-encodings.py' from 'C:\\Users\\botblake\\Documents\\test_stuff\\.venv\\Lib\\site-packages\\PyInstaller\\hooks'
10910 INFO: Processing standard module hook 'hook-pickle.py' from 'C:\\Users\\botblake\\Documents\\test_stuff\\.venv\\Lib\\site-packages\\PyInstaller\\hooks'
13495 INFO: Caching module dependency graph...
13591 INFO: Analyzing C:\Users\botblake\Documents\test_stuff\main.py
13598 INFO: Processing module hooks (post-graph stage)...
13606 INFO: Performing binary vs. data reclassification (1 entries)
13608 INFO: Looking for ctypes DLLs
13618 INFO: Analyzing run-time hooks ...
13621 INFO: Including run-time hook 'pyi_rth_inspect.py' from 'C:\\Users\\botblake\\Documents\\test_stuff\\.venv\\Lib\\site-packages\\PyInstaller\\hooks\\rthooks'
13642 INFO: Creating base_library.zip...
13712 INFO: Looking for dynamic libraries
14165 INFO: Extra DLL search directories (AddDllDirectory): []
14166 INFO: Extra DLL search directories (PATH): []
15044 INFO: Warnings written to C:\Users\botblake\Documents\test_stuff\build\oldpython\warn-oldpython.txt
15070 INFO: Graph cross-reference written to C:\Users\botblake\Documents\test_stuff\build\oldpython\xref-oldpython.html       
15140 INFO: checking PYZ
15140 INFO: Building PYZ because PYZ-00.toc is non existent
15141 INFO: Building PYZ (ZlibArchive) C:\Users\botblake\Documents\test_stuff\build\oldpython\PYZ-00.pyz
15455 INFO: Building PYZ (ZlibArchive) C:\Users\botblake\Documents\test_stuff\build\oldpython\PYZ-00.pyz completed successfully.
15468 INFO: checking PKG
15468 INFO: Building PKG because PKG-00.toc is non existent      
15468 INFO: Building PKG (CArchive) oldpython.pkg
30406 INFO: Building PKG (CArchive) oldpython.pkg completed successfully.
30411 INFO: Bootloader C:\Users\botblake\Documents\test_stuff\.venv\Lib\site-packages\PyInstaller\bootloader\Windows-64bit-intel\run.exe
30412 INFO: checking EXE
30412 INFO: Building EXE because EXE-00.toc is non existent      
30412 INFO: Building EXE from EXE-00.toc
30421 INFO: Copying bootloader EXE to C:\Users\botblake\Documents\test_stuff\dist\oldpython.exe
30460 INFO: Copying icon to EXE
30478 INFO: Copying 0 resources to EXE
30478 INFO: Embedding manifest in EXE
30492 INFO: Appending PKG archive to EXE
30599 INFO: Fixing EXE headers
32594 INFO: Building EXE from EXE-00.toc completed successfully.
32598 INFO: Build complete! The results are available in: C:\Users\botblake\Documents\test_stuff\dist

Running the built binary results in:

.\oldpython.exe
Normal Connect
Traceback (most recent call last):
  File "main.py", line 11, in <module>
SystemError: <built-in function connect> returned NULL without setting an exception
<built-in function connect> returned NULL without setting an exception

Line 11 in main.py is: db_connection = ibm_db.connect(creds.database, creds.username, creds.password)

Kind regards

[Earammak]

@BotBlake ,
Could you please try the following steps:

1. Fresh install of ibm_db:
   pip uninstall ibm_db
pip install ibm_db
2. Update your main.py:
   Replace your RTClient path with the clidriver\bin path from site‑packages:
   dll_path = r"<your_python_or_venv_path>\Lib\site-packages\clidriver\bin" os.add_dll_directory(dll_path) import ibm_db
3. Rebuild and test:
   Use your existing build.py to rebuild the executable and then test the .exe.

Thanks

[BotBlake]

@Earammak

I followed your advise. Note that the clidriver shipped with ibm_db is not configured for my setup.
This is why I specifically want to point it to the already existing, functional cli driver.

Pointing it to the new clidriver results in:

Exception: [IBM][CLI Driver] SQL1531N  The connection failed because the name specified with the DSN connection string keyword could not be found in either the db2dsdriver.cfg configuration file or the db2cli.ini configuration file.  Data source name specified in the connection string: "{creds.database}".  SQLCODE=-1531

Note that I redacted the actual connection keyword and replaced it with {creds.database} in the stack trace.

I dont think the clidriver is the issue, as it wont be included in the .exe package anyways.
Kind regards

[Earammak]

@BotBlake ,

Please check your connection string.
If you’re using a DSN, make sure that DSN is defined in either db2dsdriver.cfg or db2cli.ini.
If you don’t want to use DSN, switch to a full connection string with hostname, port, database, user, and password.
And verify your configuration files
Locate db2dsdriver.cfg or db2cli.ini inside site-packages/clidriver/cfg.
Ensure your DSN entry exists and matches the name you’re using in the connection string.

Thanks