bulkcopy() fails with SQL error 7339 for UTF-8 multibyte characters against Fabric Warehouse

The failing call is cursor.bulkcopy() with a non-ASCII value bound to a VARCHAR(100) column in a Latin1_General_100_BIN2_UTF8 Fabric Warehouse; the parameterized INSERT with the same string succeeds, so compare the two encoding paths. The payload names the mssql-python 1.16.0 package and the mssql-python-rs runtime, so start there to see how bulk data is encoded for varchar. Done means the reproduction inserts 'sofá' through bulkcopy and reads back the same value, and the ASCII control still passes.

Environment

mssql-python: 1.16.0
Python: 3.13.16
Target: Microsoft Fabric Warehouse
Authentication: ActiveDirectoryServicePrincipal
Microsoft ODBC Driver installed: 18.6.1.1
Target database collation: Latin1_General_100_BIN2_UTF8
Target column: VARCHAR(100)

Parameterized INSERT:
"/search/Individual sofá" succeeds

cursor.bulkcopy():
The same hardcoded Python string fails with SQL error 7339.
"Sql Error: 7339: Class 16: State 1: OLE DB provider 'STREAM' for linked server '(null)' returned invalid data for column"

ASCII control:
"/search/Individual sofa" succeeds.

Failing character:
á

Python UTF-8:
Characters = 23
Bytes = 24
Hex for ó = c3 b3

Target table:

DROP TABLE IF EXISTS [dbo].[BulkCopyUnicodeTest];
CREATE TABLE [dbo].[BulkCopyUnicodeTest]
(
    [Field1] VARCHAR(100) NULL
);

Successful parameterized INSERT

unicode_value = "/search/Individual sofá"
fabric_cursor.execute(
    """
    INSERT INTO [dbo].[BulkCopyUnicodeTest] ([Field1])
    VALUES (?);
    """,
    (unicode_value,),
)
fabric_connection.commit()

The stored result: /search/Individual sofá

---

The following code fails with SQL error 7339:

unicode_value = "/search/Individual sofá"
result = fabric_cursor.bulkcopy(
    table_name="[dbo].[BulkCopyUnicodeTest]",
    data=[(unicode_value,)],
    column_mappings=[(0, "Field1")],
    batch_size=0,
    timeout=300,
    keep_nulls=True,
)
fabric_connection.commit()

Error:

RuntimeError: Sql Error: 7339: Class 16: State 1:
OLE DB provider 'STREAM' for linked server '(null)'
returned invalid data for column '[!BulkInsert].Field1'.

The following code succeed

#Replacing á with ASCII o allows the bulk copy to succeed:
ascii_value = "/search/Individual sofa"
fabric_cursor.execute("TRUNCATE TABLE [dbo].[BulkCopyUnicodeTest];")
fabric_connection.commit()

result = fabric_cursor.bulkcopy(
    table_name="[dbo].[BulkCopyUnicodeTest]",
    data=[(ascii_value,)],
    column_mappings=[(0, "Field1")],
    batch_size=0,
    timeout=300,
    keep_nulls=True,
)
fabric_connection.commit()
print(result)

---

Encoding details

unicode_value = "/search/Individual sofá"
print(len(unicode_value))
print(len(unicode_value.encode("utf-8")))
print(unicode_value.encode("utf-8").hex(" "))

Output

23
24
2f 73 65 61 72 63 68 2f 49 6e 64 69 76 69 64 75 61 6c 20 73 6f 66 c3 b3

---

python -m pip show mssql-python mssql-python-rs mssql-python-odbc

Name: mssql-python
Version: 1.16.0
Summary: A Python library for interacting with Microsoft SQL Server
Home-page: https://github.com/microsoft/mssql-python
Author: Microsoft Corporation
Author-email: [email protected]
License:
Requires: azure-identity, mssql-python-odbc, mssql-python-rs
Required-by:

Name: mssql-python-rs
Version: 0.3.0
Summary: Rust-based native runtime (TDS core and ODBC driver) consumed by the mssql-python driver.
Home-page: https://github.com/microsoft/mssql-python
Author: Microsoft Corporation
Author-email:
License: MIT
Requires:
Required-by: mssql-python

Name: mssql-python-odbc
Version: 18.6.2.2
Summary: Internal implementation package for mssql-python: Microsoft ODBC Driver 18 for SQL Server binaries. Not intended for direct use.
Home-page: https://github.com/microsoft/mssql-python
Author: Microsoft Corporation
Author-email: [email protected]
License: Other/Proprietary License
Requires:
Required-by: mssql-python

---

Complete snippet

from contextlib import closing
import mssql_python

CLIENT_ID = ""
CLIENT_SECRET = ""

WAREHOUSE_SERVER = ""
WAREHOUSE_NAME = ""

FABRIC_CONNECTION_STRING = (
    f"Server={WAREHOUSE_SERVER};"
    f"Database={WAREHOUSE_NAME};"
    "Authentication=ActiveDirectoryServicePrincipal;"
    f"UID={CLIENT_ID};"
    f"PWD={CLIENT_SECRET};"
    "Encrypt=yes;"
    "TrustServerCertificate=no;"
)

TABLE_NAME = "[dbo].[BulkCopyUnicodeTest]"
UNICODE_VALUE = "/search/Individual sofá"
ASCII_VALUE = "/search/Individual sofa"

with closing(mssql_python.connect(FABRIC_CONNECTION_STRING)) as fabric_connection:
    with closing(fabric_connection.cursor()) as fabric_cursor:

        fabric_cursor.execute(f"DROP TABLE IF EXISTS {TABLE_NAME};")

        fabric_cursor.execute(f"""
            CREATE TABLE {TABLE_NAME}
            (
                [Field1] VARCHAR(100) NULL
            );
        """)

        fabric_connection.commit()

        # Parameterized INSERT succeeds.
        fabric_cursor.execute(
            f"""
            INSERT INTO {TABLE_NAME} ([Field1])
            VALUES (?);
            """,
            (UNICODE_VALUE,),
        )

        fabric_connection.commit()

        fabric_cursor.execute(f"SELECT [Field1] FROM {TABLE_NAME};")
        print(f"Parameterized INSERT stored: {fabric_cursor.fetchone()[0]}")

        # Clear the table before testing bulkcopy.
        fabric_cursor.execute(f"TRUNCATE TABLE {TABLE_NAME};")
        fabric_connection.commit()

        # ASCII bulkcopy control succeeds.
        ascii_result = fabric_cursor.bulkcopy(
            table_name=TABLE_NAME,
            data=[(ASCII_VALUE,)],
            column_mappings=[(0, "Field1")],
            batch_size=0,
            timeout=300,
            keep_nulls=True,
        )

        fabric_connection.commit()

        print(f"ASCII bulkcopy succeeded: {ascii_result}")

        # Clear the table before testing the Unicode value.
        fabric_cursor.execute(f"TRUNCATE TABLE {TABLE_NAME};")
        fabric_connection.commit()

        print(f"Unicode characters: {len(UNICODE_VALUE)}")
        print(f"Unicode UTF-8 bytes: {len(UNICODE_VALUE.encode('utf-8'))}")
        print(f"Unicode UTF-8 hex: {UNICODE_VALUE.encode('utf-8').hex(' ')}")

        # Unicode bulkcopy fails with SQL error 7339.
        unicode_result = fabric_cursor.bulkcopy(
            table_name=TABLE_NAME,
            data=[(UNICODE_VALUE,)],
            column_mappings=[(0, "Field1")],
            batch_size=0,
            timeout=300,
            keep_nulls=True,
        )
        fabric_connection.commit()

        print(f"Unicode bulkcopy succeeded unexpectedly: {unicode_result}")