Skip to main content

Troubleshooting

Having trouble with Cruxstack Node SDK? Here are common issues and solutions.

Common Issues​

1. "SDK not initialized. Call init() first."​

  • Solution: Ensure you call init({ clientId }) once at app startup.

2. "Category name is required and must be a non-empty string"​

  • Solution: Pass a valid, non-empty string as the first argument to cruxTrack.

3. "Event tracking failed: ..."​

  • Solution: Validate your event payload shape. Include tenant context per event if needed (customerId, customerName).

4. "Failed to send event: ..."​

  • Solution: Usually a network/API error. SDK retries automatically. If persistent, verify network access to dev-api.cruxstack.com and confirm clientId.

5. Events not appearing in analytics​

  • Solution: Check the retry queue with getQueueSize(). If events are stuck, use clearQueue() and try again.

6. Trait lookup errors​

  • Messages: "userIds is required", "At least one userId is required", "All userIds must be non-empty strings", "customerId is required for getUserTraits"
  • Solution: Provide a string or string[] of user IDs and pass the customerId for the tenant to query.

Debugging Tips​

  • Use console.log to inspect event data before sending.
  • Confirm clientId is correct.
  • Ensure you pass customerId per event and for trait lookups when required.
  • Review error messages for hints.

Still Stuck?​