/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](https://support.google.com/analytics/answer/7201382) | | Meta | [Facebook Pixel Helper](https://developers.facebook.com/docs/meta-pixel/support/pixel-helper) | | Plausible | [Plausible Dashboard real-time](https://plausible.io/docs) |

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({ name: 'product view', data: { 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 });

Simulated Destination Recorded Nothing: Pending vs Consent Skip

`walkeros push flow.json -e event.json --simulate destination.X` prints why a destination sent nothing, from the collector's own records (`--json` and MCP: `skipped` on the result):

| Line (`skipped`) | Meaning | Fix in simulate | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `pending: waits for consent (require)` (`{ reason: 'pending', require: ['consent'] }`) | `require: ["consent"]`: never started, no consent state exists | `--consent '{"functional":true}'` (MCP `state.consent`) | | `skipped: consent (requires marketing; granted functional)` (`{ reason: 'consent', required, granted }`) | Started, but `config.consent` denied the event (collector + event consent) | Grant the key in `--consent` or the event's `consent` | | `mapping: none (skipped before mapping)`, no `skipped` line | Not consent: a filter, a `before` chain stop, or an error | Check `--verbose` logs, the `before` chain and the mapping rules |

`require` checks that consent state is present at all; `config.consent` checks each event's keys. `--consent` is the collector's starting state: any value clears the consent `require`, and its granted keys f