Common Issues

Symptoms:

• client.start() succeeds, but no event callbacks fire.

Checks:

• Marketplace endpoint URL points to correct module port.
• Endpoint includes /zoom/events suffix.
• webhooksSecretToken matches app configuration.
• Ngrok forward is active and mapped to the receiver port.

OAuth install/callback fails

Symptoms:

• Install page redirects fail or callback errors.

Checks:

• installerOptions.redirectUri exactly matches Marketplace OAuth redirect.
• stateStore value is configured and stable.
• Receiver mode supports User OAuth (Lambda receiver caveat).

Multi-module runtime conflicts

Symptoms:

• One module works, another silently fails.

Checks:

• Every module uses a unique port.
• Event subscriptions target the correct module endpoint.
• Env variables are not accidentally shared with wrong module.

API-only mode confusion

Symptoms:

• OAuth expectations fail when receiver disabled.

Checks:

• disableReceiver: true disables OAuth flow behavior.
• For OAuth + API-only behavior, use receiver-compatible configuration and relax webhook verification as documented.

Sample parity mismatches

Symptoms:

• Following sample exactly still fails in your environment.

Checks:

• Normalize env key names to your project standard.
• Reconcile sample README assumptions with current TypeDoc signatures.
• Verify module auth type alignment (Client Credentials vs User OAuth vs S2S).