walkeros-debugging

name	walkeros-debugging
description	Use when walkerOS events aren't reaching destinations, debugging event flow, or troubleshooting mapping issues. Covers common problems and debugging strategies.

Debugging walkerOS Events

Quick Diagnosis

Symptom	Likely Cause	Check
No events at all	Source not initialized	Console for errors, verify startFlow()
Events fire but destination silent	Mapping mismatch	Event name matches mapping?
Partial data missing	Path doesn't exist	Log event structure, check nested paths
Consent blocking	Required consent not granted	Check consent config, grant consent
Destination error	Vendor API issue	Check network tab, vendor console

Debugging Strategies

1. Console Logging

Log all events at collector level:

import { startFlow } from '@walkeros/collector';

const { elb } = await startFlow({
  destinations: {
    debug: {
      push: async (event, context) => {
        console.log('[walkerOS Event]', {
          name: event.name,
          data: event.data,
          context: event.context,
          consent: event.consent,
          timestamp: event.timestamp,
        });
      },
      config: {},
    },
    // ... other destinations
  },
});

2. Network Tab Inspection

For destinations that make HTTP calls:

1. Open DevTools → Network tab
2. Filter by destination domain (e.g., google-analytics.com, facebook.com)
3. Trigger event
4. Inspect request payload

What to look for:

• Request being made at all?
• Correct endpoint URL?
• Payload structure matches vendor spec?

3. Vendor Debug Tools

Vendor	Debug Tool
GA4	GA4 DebugView
Meta	Facebook Pixel Helper
Plausible	Plausible Dashboard real-time

4. Dry Run Mode

Test mapping without sending to vendor:

const destination = {
  ...actualDestination,
  config: {
    ...actualDestination.config,
    dryRun: true, // Events processed but not sent
  },
};

Common Issues

Event Name Mismatch

Problem: Event fires but destination doesn't receive it.

// Event pushed
elb('product view', { id: 'P123' });

// Mapping expects different name
mapping: {
  Product: {
    // Wrong: capital P
    View: {
      // Wrong: capital V
      name: 'view_item';
    }
  }
}

Fix: Event names are case-sensitive. Use exact match:

mapping: {
  product: {
    view: {
      name: 'view_item';
    }
  }
}

Missing Nested Data

Problem: items array is empty in destination.

// Event structure
{
  name: 'order complete',
  data: { total: 100 },
  nested: [
    { entity: 'product', data: { id: 'P1' } }
  ]
}

// Mapping tries wrong path
data: {
  map: {
    items: {
      loop: [
        'data.items',  // Wrong: nested is at root, not in data
        { map: { id: 'data.id' } }
      ]
    }
  }
}

Fix: Use correct path to nested array:

items: {
  loop: [
    'nested', // Correct: root-level nested
    { map: { item_id: 'data.id' } },
  ];
}

Consent Blocking Events

Problem: Events not reaching destination.

Check 1: Does destination require consent?

// Destination config
config: {
  consent: {
    marketing: true;
  } // Requires marketing consent
}

Check 2: Is consent granted?

// Check current consent state
console.log(event.consent);

// Grant consent
elb('walker consent', { marketing: true });

Vendor SDK Not Loaded

Problem: TypeError: env.window.gtag is not a function

Cause: Vendor script not loaded before push.

Fix: Ensure init() loads script:

init: async (config, env) => {
  // Wait for script to load
  await loadScript('https://vendor.com/sdk.js');
  // Verify SDK available
  if (!env.window.vendorSdk) {
    throw new Error('Vendor SDK failed to load');
  }
},

Function Mapping Errors

Problem: Cannot read property 'price' of undefined

// Mapping with unsafe access
data: {
  map: {
    value: {
      fn: (e) => e.data.price * 100;
    } // Fails if data.price undefined
  }
}

Fix: Add null checks:

value: {
  fn: (e) => (e.data?.price ?? 0) * 100;
}

Debugging Checklist

When events aren't working:

1. Console errors? Check browser console for exceptions
2. Event pushed? Add debug destination to log all events
3. Mapping matched? Verify entity/action names exactly match
4. Data paths correct? Log full event structure, verify paths exist
5. Consent granted? Check consent requirements and state
6. SDK loaded? Verify vendor script loaded before push
7. Network request? Check DevTools network tab
8. Vendor receiving? Use vendor debug tools

Testing in Isolation

Test destination push directly:

import { push } from '@walkeros/web-destination-gtag';
import { mockEnv } from '@walkeros/core';

// Create test event
const event = {
  name: 'product view',
  data: { id: 'P123', price: 99 },
  // ... full event
};

// Mock env to capture calls
const calls = [];
const testEnv = mockEnv(baseEnv, (path, args) => {
  calls.push({ path, args });
});

// Test push directly
await push(event, { config: testConfig, env: testEnv });

// Inspect what was called
console.log(calls);

MCP Tool Debugging

When using walkerOS MCP tools, check _hints.warnings in tool responses for diagnostic information:

• flow_simulate warns when 0 destinations exist or none received the event. step is required (e.g. "destination.gtag"). Source steps take a { content, trigger? } event where content is { name, data }; sources, including @walkeros/source-demo, can be simulated this way.
• flow_bundle warns when the build produces no output
• flow_examples warns when no examples are found in the config
• package_search returns the complete catalog and warns (via the warnings array) when it falls back to a partial source or omits packages, instead of silently returning a partial list
• All error responses include a hint field with recovery suggestions

When a request fails or behaves unexpectedly, call diagnostics (read-only, no parameters, works logged out). It reports the MCP and CLI versions, the resolved app URL and whether it came from WALKEROS_APP_URL or the default, app /api/health reachability, the bundled OpenAPI contract version, and which source served the last package lookup, so you can tell which backend and versions you are on.

Related Skills

• walkeros-understanding-flow - Event flow architecture
• walkeros-understanding-destinations - Destination interface
• walkeros-mapping-configuration - Mapping recipes