Installing Teradata Parallel Transporter (TPT) Kafka Connector in WSL

Jan 22

Installation, Common Errors, and How to Fix Them (Ubuntu / WSL)

Kafka is a common integration point for modern data platforms, and Teradata provides a Kafka Access Module for TPT to consume messages directly into Teradata using high-performance load operators.

This post walks through:

Installing the Teradata Kafka Access Module
Verifying the environment
The most common runtime failures
Why they happen
How to fix them cleanly

If you’ve ever seen libsasl2.so.3 errors or mysterious pmAttach failed messages, this post is for you.

1. What Is the TPT Kafka Access Module?

The Kafka Access Module (KAFKA_AXSMOD) allows TPT producer operators to consume Kafka messages directly, without writing custom consumers.

At a high level:

Kafka Topic
   ↓
Kafka Access Module (AXSMOD)
   ↓
TPT Producer Operator
   ↓
Teradata LOAD / STREAM / UPDATE

Key characteristics:

Built on librdkafka
Supports PLAINTEXT, TLS, SASL (depending on configuration)
Designed and certified primarily for RHEL / Oracle Linux

That last point matters more than you might expect with WSL, Ubuntu.

2. Prerequisites

Before starting, ensure you have:

Teradata Client Utilities installed (TPT included)
Kafka broker reachable (local or remote)
Kafka topic already created
Ubuntu or WSL environment (this blog focuses here)
Access to /opt/teradata/client/<version>/

Check TPT:

tbuild -V

3. Installing the Kafka Access Module

The Kafka Access Module is not enabled by default with TPT.

After installing Teradata Client Utilities, (./setup.sh) verify the module exists:

ls /opt/teradata/client/*/axsmod/lib | grep kafka

You should see something like:

libkafkaaxsmod.so

If not:

Re-run the Teradata client installer
Ensure “Access Modules” were selected

4. Validating Kafka Connectivity (Before TPT)

Before debugging TPT, validate Kafka independently.

From the same machine:

kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 \
  --topic test-topic \
  --from-beginning

If this fails, stop here.
TPT will not fix Kafka connectivity issues.

5. Ubuntu / WSL: Fixing the `libsasl2.so.3` Error

(The #1 Issue Everyone Hits)

If you are running TPT Kafka on Ubuntu or WSL, you will almost certainly encounter this error:

TPT19434 pmAttach failed. General failure (34):
'!ERROR! dlopen failed: libsasl2.so.3: cannot open shared object file'

This error happens before Kafka is even contacted.

Why This Happens

The Kafka Access Module is:

Built against RHEL-based distributions
Dynamically linked to Cyrus SASL v3

On RHEL, the following library exists:

libsasl2.so.3

On Ubuntu (including WSL), Cyrus SASL is version 2, which provides:

libsasl2.so.2

Even though SASL is installed, the loader fails because the SONAME does not match.

Confirm this:

ls /usr/lib/x86_64-linux-gnu | grep sasl

Typical output:

libsasl2.so.2
libsasl2.so.2.0.25
sasl2

Why `apt install` Will Not Fix This

Trying:

sudo apt install libsasl2-3

Fails because:

Ubuntu does not ship a v3 package
There is no backport
This is an ABI naming difference, not missing functionality

The Correct Fix: Compatibility Symlink

Create a compatibility symlink so the loader can resolve the dependency:

sudo ln -s /usr/lib/x86_64-linux-gnu/libsasl2.so.2 \
           /usr/lib/x86_64-linux-gnu/libsasl2.so.3
sudo ldconfig

This tells the system:

“When something requests libsasl2.so.3, use the existing v2 library.”

Why This Is Safe

Cyrus SASL v2 provides all required symbols
No system libraries are replaced
This is a standard enterprise Linux workaround
Fully reversible

To undo:

sudo rm /usr/lib/x86_64-linux-gnu/libsasl2.so.3
sudo ldconfig

Verifying the Fix

Check dependencies:

ldd /opt/teradata/client/*/axsmod/lib/libkafkaaxsmod.so

Before:

libsasl2.so.3 => not found

After:

libsasl2.so.3 => /usr/lib/x86_64-linux-gnu/libsasl2.so.3

Once this resolves, pmAttach errors disappear.

6. Kafka Configuration Warnings (What to Ignore)

You may see warnings like:

compression.codec is a producer property and will be ignored

or:

allow.auto.create.topics=false not supported by broker

These are non-fatal and safe to ignore unless:

You rely on broker auto-creation
You expect compression at the consumer side

They do not prevent message consumption.

7. Message Size & Block Size Errors

A common runtime failure:

Message Length is greater than Block size

This means:

Kafka messages are larger than TPT’s buffer
Or messages are JSON blobs without delimiters

Solutions:

Increase BlockSize
Ensure messages are properly delimited
Avoid large single-record JSON payloads

8. Data Format Errors (EOF / EOR)

Error message:

Unexpected or invalid data formatting was detected

Causes:

Missing record delimiters
Incorrect Format setting
JSON without consistent boundaries

Kafka messages must align with TPT’s record expectations.

TPT does not natively parse JSON structures—it reads records.

9. Checkpoint File Errors

Error: Cannot get the current job step from the Checkpoint file

This usually means:

Schema or operator definitions changed
The checkpoint file is stale

Fix:

rm /opt/teradata/client/*/tbuild/checkpoint/<jobname>*

Then rerun the job.

10. Key Takeaways

Most Kafka + TPT failures on Ubuntu are not Kafka problems
libsasl2.so.3 is the biggest blocker—and easy to fix
Validate Kafka independently before touching TPT
TPT reads records, not JSON objects
Clear checkpoints when modifying job scripts

Final Thoughts

The Teradata Kafka Access Module is powerful, but it assumes:

RHEL-like environments
Traditional record-oriented data

Once you understand those assumptions, Kafka + TPT becomes predictable and stable—even on WSL.

If this blog saves you a few hours of debugging, it’s done its job.

James Armitage