Setting the file. One moment.
Skill 125 · Zoom Meeting SDK Web
Subchapter 125.13
troubleshooting/common-issues.mdMarkdown10 KBView on GitHub
Quick diagnostics and solutions for the most common issues.
References
Component View Breakout RoomsAlso bundled
Browser Support1. Check browser console for errors
2. Verify signature is valid and not expired
3. Check COOP/COEP headers for HD features
4. Verify SDK version is supported
5. Test in Chrome/Edge first (most compatible)Symptom: SDK throws error when trying to join.
Cause: join() called before init() completed.
Solution:
// WRONG
ZoomMtg.init({ leaveUrl: '...' });
ZoomMtg.join({ ... }); // Too early!
// CORRECT
ZoomMtg.init({
leaveUrl: '...',
success: () => {
ZoomMtg.join({ ... }); // Wait for success callback
}
});Symptom: ZoomMtg is not defined
Cause: Scripts not loaded in correct order.
Solution:
<!-- Load in this exact order -->
<script src="https://source.zoom.us/{VERSION}/lib/vendor/react.min.js"></script>
<script src="https://source.zoom.us/{VERSION}/lib/vendor/react-dom.min.js"></script>
<script src="https://source.zoom.us/{VERSION}/lib/vendor/redux.min.js"></script>
<script src="https://source.zoom.us/{VERSION}/lib/vendor/redux-thunk.min.js"></script>
<script src="https://source.zoom.us/{VERSION}/lib/vendor/lodash.min.js"></script>
<script src="https://source.zoom.us/zoom-meeting-{VERSION}.min.js"></script>Symptom: SDK hangs or UI shows wrong language.
Cause: init() called before language loaded.
Solution:
ZoomMtg.i18n.load('en-US');
ZoomMtg.i18n.onLoad(() => {
// ONLY init after language is loaded
ZoomMtg.init({ ... });
});Symptom: Join fails with signature error.
Causes & Solutions:
Wrong SDK Secret
# Verify in Zoom Marketplace > App > App CredentialsSignature expired
// Check signature expiration (default 2 hours)
// Regenerate signature if neededMissing appKey prefix (v5.0.0+)
// WRONG (pre-5.0 format)
signature: "eyJhbGc..."
// CORRECT (5.0+ format)
signature: "appKey:sdkKey.eyJhbGc..."Wrong algorithm
// MUST use HS256
jwt.sign(payload, secret, { algorithm: 'HS256' });Symptom: SDK Key rejected.
Causes:
Solution: Verify SDK Key in Zoom Marketplace matches exactly.
Symptom: Previously working key now fails.
Cause: App deactivated in Marketplace.
Solution:
Symptom: Join fails with password error even with correct password.
Cause: Different spelling between views!
Solution:
// Client View - capital W
ZoomMtg.join({
passWord: 'meeting123', // Capital W!
});
// Component View - lowercase
client.join({
password: 'meeting123', // lowercase!
});Symptom: Valid meeting number rejected.
Causes & Solutions:
Wrong meeting number
Meeting deleted or expired
Meeting not started yet
Symptom: Correct password rejected.
Causes:
Solution:
// Extract password correctly from invite link
const url = new URL(inviteLink);
const password = url.searchParams.get('pwd');Symptom: Can’t join new meeting.
Cause: User already in another SDK meeting instance.
Solution:
// Leave current meeting first
ZoomMtg.leaveMeeting({});
// Then join new meetingSymptom: Video stuck at low resolution.
Cause: SharedArrayBuffer not available.
Diagnostic:
console.log('Cross-origin isolated:', window.crossOriginIsolated);
console.log('SharedArrayBuffer:', typeof SharedArrayBuffer === 'function');Solution: Add COOP/COEP headers:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corpSee concepts/sharedarraybuffer.md for details.
Symptom: Virtual background option missing or grayed out.
Causes:
Solution:
// Check support first
ZoomMtg.isSupportVirtualBackground({
success: (data) => {
if (data.result.isSupport) {
// VB supported
} else {
console.log('VB not supported:', data.result.reason);
}
}
});Symptom: inMeetingServiceListener events never trigger.
Causes & Solutions:
Registered too late
// Register BEFORE or AFTER init, but make sure SDK is ready
ZoomMtg.inMeetingServiceListener('onUserJoin', callback);Wrong event name
// Event names are case-sensitive
'onUserJoin' // Correct
'OnUserJoin' // Wrong
'on-user-join' // WrongMeeting not fully joined
// Wait for join success before expecting events
ZoomMtg.join({
success: () => {
// Now events will fire
}
});Symptom: client.on() callbacks never trigger.
Solution:
// Component View uses different event names
client.on('connection-change', callback); // Not 'onMeetingStatus'
client.on('user-added', callback); // Not 'onUserJoin'
client.on('user-removed', callback); // Not 'onUserLeave'Symptom: Screen share option missing on Safari.
Cause: Requires Safari 17+ with macOS Sonoma for Client View.
Solution:
Symptom: Video issues on Firefox.
Cause: Firefox uses different WebRTC implementation.
Solution: Test in Chrome first, then adapt for Firefox.
Symptom: Features missing on mobile.
Reality: These features are NOT supported on mobile browsers:
Solution: Detect mobile and adjust UI accordingly:
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
if (isMobile) {
// Hide unsupported feature buttons
}Symptom: SDK resources blocked.
Solution 1: Use helper.html
ZoomMtg.init({
helper: './helper.html',
// ...
});Solution 2: Configure CSP headers
Content-Security-Policy:
script-src 'self' 'unsafe-inline' 'unsafe-eval' https://zoom.us *.zoom.us blob:;
connect-src 'self' https://zoom.us https://*.zoom.us wss://*.zoom.us;Symptom: “Failed to load WebAssembly module”
Cause: WASM files blocked by CSP.
Solution: Add wasm-unsafe-eval or unsafe-eval to script-src:
script-src 'self' 'wasm-unsafe-eval' ...Symptom: Multiple SDK instances, memory leaks.
Cause: createClient() in component body.
Solution:
// WRONG
function App() {
const client = ZoomMtgEmbedded.createClient(); // Created every render!
}
// CORRECT
function App() {
const clientRef = useRef<typeof client | null>(null);
useEffect(() => {
if (!clientRef.current) {
clientRef.current = ZoomMtgEmbedded.createClient();
}
}, []);
}Symptom: Error when initializing Component View.
Cause: Container element not ready.
Solution:
// WRONG
await client.init({
zoomAppRoot: document.getElementById('meeting'), // Might be null
});
// CORRECT (React)
const containerRef = useRef<HTMLDivElement>(null);
useEffect(() => {
if (containerRef.current) {
client.init({ zoomAppRoot: containerRef.current });
}
}, []);
return <div ref={containerRef} />;Causes & Solutions:
Not preloading WASM
// Call early, before user clicks join
ZoomMtg.preLoadWasm();
ZoomMtg.prepareWebSDK();Network latency
assetPathLarge bundle
Symptom: Browser memory grows over time.
Causes:
Solution:
ZoomMtg.init({
leaveOnPageUnload: true, // Auto cleanup
});Client View:
ZoomMtg.init({
debug: true, // Logs to console
});Component View:
client.init({
debug: true,
});// Use vConsole for mobile debugging
if (/iPhone|iPad|iPod|Android/i.test(navigator.userAgent)) {
const vConsole = new VConsole();
}