/partner-built/zoom-plugin/skills/video-sdk/linux/troubleshooting/common-issues.md

Common Issues and Solutions

Session Join Issues

Issue: "Failed to join session" (no error details)

Causes:

1. Invalid JWT token
2. Session name doesn't match JWT tpc claim
3. Wrong SDK credentials
4. Expired token

Solution:

# Regenerate JWT token
import jwt
import time

payload = {
    "app_key": SDK_KEY,
    "iat": int(time.time()) - 30,
    "exp": int(time.time()) + 7200,
    "tpc": "exact-session-name",  # MUST match sessionName
    "role_type": 1  # 0=participant, 1=host
}
token = jwt.encode(payload, SDK_SECRET, algorithm="HS256")

Issue: "Authentication failed"

Solution: Verify SDK_KEY and SDK_SECRET in JWT generation.

Issue: Session requires password

Solution:

session_context.sessionPassword = "password";

Audio Issues

Issue: No audio callbacks

Cause: PulseAudio not configured.

Solution: See PulseAudio Setup.

Issue: Audio on headless Linux

Solution: Use virtual audio:

session_context.virtualAudioSpeaker = new VirtualSpeaker();
session_context.virtualAudioMic = new VirtualMic();

Video Issues

Issue: "Linux has no Canvas API!"

Solution: Use Raw Data Pipe. See Raw Data vs Canvas.

Issue: Video frames not received

Cause: Not subscribing to user's video pipe.

Solution:

void onUserVideoStatusChanged(..., IVideoSDKVector<IZoomVideoSDKUser*>* userList) override {
    for (int i = 0; i < userList->GetCount(); i++) {
        IZoomVideoSDKUser* user = userList->GetItem(i);
        IZoomVideoSDKRawDataPipe* pipe = user->GetVideoPipe();
        pipe->subscribe(ZoomVideoSDKResolution_720P, videoDelegate);
    }
}

Build Issues

Issue: "libQt5Core.so.5: not found"

Solution: See Qt Dependencies.

Issue: Undefined reference to SDK symbols

Solution: See Build Errors.

Memory Issues

Issue: Crashes with large video frames

Solution: Use heap memory mode:

init_params.videoRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;

SDK Init Error 7 (Invalid_Parameter)

sdk->initialize(initParams) returns error code 7 when:

1. Domain is wrong - Must be "https://zoom.us" (with protocol). Plain "zoom.us" causes error 7.
2. PulseAudio is not running - Headless Linux requires PulseAudio. See PulseAudio Setup.
3. Missing ~/.config/zoomus.conf - Must exist with content:

   [General]
   system.audio.type=default
   

GLib Main Loop Required

The SDK internally uses Qt/GLib for event dispatching. A while (running) { sleep(500ms); } loop does NOT work — onSessionJoin and all other delegate callbacks will never fire.

You MUST use a GLib main loop:

#include <glib.h>

static GMainLoop* loop = nullptr;

gboolean timeout_callback(gpointer data) {
    return TRUE;
}

loop = g_main_loop_new(NULL, FALSE);
g_timeout_add(100, timeout_callback, loop);
g_main_loop_run(loop);

if (loop) g_main_loop_quit(loop);

See Session Join Pattern for the complete working example.

All SDK Calls Must Be Made from the Main Thread

ALL Zoom Video SDK API calls must be called from the GLib main thread. Calling SDK methods from a std::thread or any background thread returns ZoomVideoSDKErrors_Internal_Error (error code 2).

Use g_idle_add() to schedule SDK calls from background threads:

struct CallContext {
    IZoomVideoSDK* sdk;
    std::string data;
};

static gboolean executeOnMainThread(gpointer data) {
    auto* ctx = static_cast<CallContext*>(data);
    // Make SDK calls here — this runs on the GLib main thread
    delete ctx;
    return G_SOURCE_REMOVE;
}

// From a background thread:
auto* ctx = new CallContext{sdk_, someData};
g_idle_add(executeOnMainThread, ctx);

g_idle_add() is thread-safe — it queues work onto the GLib main loop. See Command Channel for a real-world example.

Quick Diagnostic Checklist

• PulseAudio installed and configured
• ~/.config/zoomus.conf exists
• Qt5 libraries copied from SDK
• Qt5 symlinks created
• LD_LIBRARY_PATH set correctly
• JWT token valid and not expired
• Session name matches JWT tpc claim
• All delegate methods implemented
• Using heap memory mode
• Subscribing in correct callbacks
• Domain set to "https://zoom.us" (with protocol)
• Using GLib main loop (not while/sleep loop)
• SDK calls made from main thread only (use g_idle_add from background threads)

Error Codes

Code	Name	Meaning
0	Success	Operation succeeded
1001	Auth_Error	Authentication failed
1003	Auth_Wrong_Token	Invalid JWT
1004	Auth_Expired_Token	JWT expired
3001	Session_Join_Failed	Failed to join
3008	Session_Need_Password	Password required
3009	Session_Password_Wrong	Wrong password
7	Invalid_Parameter	Wrong domain, missing PulseAudio, or missing zoomus.conf
2	Internal_Error	SDK method called from wrong thread (use g_idle_add)

Getting Help

1. Check Official Docs
2. Search Dev Forum
3. Review GitHub Samples