#Error Handling

Learn how to handle errors and debug issues in your Tode analytics implementation for Figma plugins and widgets.

#Silent Failures by Design

Tode methods are designed to fail silently to avoid disrupting your plugin's functionality. This means:

• Tracking calls won't throw errors that crash your UI
• Users won't see error messages from analytics
• Your plugin continues working even if analytics fail

#Debug Mode

Enable debug mode during development to see what's happening under the hood. This logs all tracking calls and any errors to the console.

import { tode } from '@tode-sdk/core';
 
await tode.init({
  apiKey: 'your-api-key',
  debug: true  // Enable for development
});

With debug mode enabled, you'll see console logs for:

• Initialization status
• Each tracking call
• Connection state changes
• Any errors that occur

Tip: Disable debug mode in production to keep the console clean for your users.

await tode.init({
  apiKey: 'your-api-key',
  debug: process.env.NODE_ENV === 'development'
});

#Common Issues

#Server Responses

Every tracking request answers with JSON. Success is 201 {"ok": true}. Errors carry an error code and a human-readable message:

The SDK logs these to the console and continues; your plugin never sees an exception.

#Network Configuration

Make sure your manifest.json includes the required domains and the currentuser permission:

{
  "permissions": ["currentuser"],
  "networkAccess": {
    "allowedDomains": [
      "https://processing.usetode.dev",
      "wss://processing.usetode.dev"
    ]
  }
}

Missing network access is the most common cause of tracking failures. A missing currentuser permission does not stop events, but figma.currentUser is null, so every event is anonymous and the dashboard shows no unique users.

#Session Connection

Session length comes from a WebSocket the UI adapter keeps open. If it drops, the adapter reconnects on its own: after 1s, 2s, 4s and so on, up to 30s between tries, for as long as the UI is open. When the browser reports the network is back it retries at once, so a plugin left open through laptop sleep picks up again.

Each reconnect is stored as a separate session. Read wsState (disconnected, connecting, connected, error) if you want to show the connection in your UI. Socket errors reach the console only with debug on.

#Checking Ready State

You can track before isReady is true. The SDK holds up to 50 early events and sends them when the config arrives from the plugin controller:

// In your UI code, no ready check needed
tode.trackAction('button_clicked');

The UI also asks the controller for the config when it starts listening, so a slow-loading UI, or one you close and open again with figma.showUI(), still becomes ready. Your own figma.ui.onmessage handler will see that request as { type: 'TODE_UI_READY' }; ignore message types you don't handle.

If isReady is always false:

1. Verify tode.init() is called in your plugin controller
2. Check that init() is called after figma.showUI()
3. Enable debug mode to see initialization logs
4. Verify network access is configured correctly

#Getting Help

If you're still experiencing issues:

• Review the Best Practices for correct implementation patterns
• Check your framework guide for specific setup instructions
• Enable debug mode and check browser console for errors
• Write to hello@usetode.dev with your debug logs