> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 5.3: Common Integration Pitfalls

> Diagnose and fix the most common configuration errors: slug mismatches, timing issues, data type problems, and calculation dependency failures.

<Panel>
  <Card title="Accounting Academy" className="accounting-academy-card">
    <div className="accounting-academy-content">
      <Steps className="my-0">
        <Step title="MODULE 1: Fundamentals" icon="bookmark" iconType="solid" stepNumber={1} titleSize="p">
          * [1.1: Core Concepts & the Data Lifecycle](/accounting-academy/module-1/1-1-core-concepts-data-lifecycle)
          * [1.2: Translating Methodologies to Mangrove](/accounting-academy/module-1/1-2-translating-methodologies-to-mangrove)
          * [1.3: Events and Datapoints](/accounting-academy/module-1/1-3-events-and-datapoints)
          * [Exercise: Design and Build](/accounting-academy/module-1/1-exercise-design-and-build)
        </Step>

        <Step title="MODULE 2: Calculations" icon="bookmark" iconType="solid" stepNumber={2} titleSize="p">
          * [2.1: Calculation Architecture](/accounting-academy/module-2/2-1-calculation-architecture)
          * [2.2: Expanding Your Data Model](/accounting-academy/module-2/2-2-expanding-your-data-model)
          * [Exercise: Multi-Step Calculations](/accounting-academy/module-2/2-exercise-multi-step-calculations)
        </Step>

        <Step title="MODULE 3: Batch Partitioning & LCA" icon="bookmark" iconType="solid" stepNumber={3} titleSize="p">
          * [3.1: What Is a Batch?](/accounting-academy/module-3/3-1-what-is-a-batch)
          * [3.2: Batch Partitioning Strategies](/accounting-academy/module-3/3-2-batch-partitioning)
          * [3.3: Life Cycle Assessment & Emissions](/accounting-academy/module-3/3-3-lca-and-emissions)
          * [3.4: Allocating Emissions to Batches](/accounting-academy/module-3/3-4-allocating-emissions-to-batches)
          * [Exercise: Batch Partitioning & LCA](/accounting-academy/module-3/3-exercise-batch-partitioning-and-lca)
        </Step>

        <Step title="MODULE 4: Mass Balance with Ledgers" icon="bookmark" iconType="solid" stepNumber={4} titleSize="p">
          * [4.1: Introduction to Mass Balance](/accounting-academy/module-4/4-1-intro-to-mass-balance)
          * [4.2: Designing the Ledger Structure](/accounting-academy/module-4/4-2-designing-the-ledger-structure)
          * [4.3: Multiple Batch Types for Different Stages](/accounting-academy/module-4/4-3-multiple-batch-types)
          * [Exercise: Design & Build Mass Balance](/accounting-academy/module-4/4-exercise-design-and-build-mass-balance)
        </Step>

        <Step title="MODULE 5: Integration Testing" icon="bookmark" iconType="solid" stepNumber={5} titleSize="p">
          * [5.1: The Complete Model Assembly](/accounting-academy/module-5/5-1-the-complete-model-assembly)
          * [5.2: Testing Patterns](/accounting-academy/module-5/5-2-testing-patterns)
          * [5.3: Common Integration Pitfalls](/accounting-academy/module-5/5-3-common-integration-pitfalls)
          * [Exercise: Integration Testing](/accounting-academy/module-5/5-exercise-integration-testing)
        </Step>

        <Step title="MODULE 6: Advanced Patterns & Production" icon="bookmark" iconType="solid" stepNumber={6} titleSize="p">
          * [6.1: Model Design Best Practices](/accounting-academy/module-6/6-1-model-design-best-practices)
          * [6.2: Advanced Techniques](/accounting-academy/module-6/6-2-advanced-techniques)
          * [6.3: Production Readiness](/accounting-academy/module-6/6-3-production-readiness)
          * [Exercise: Production Deployment](/accounting-academy/module-6/6-exercise-production-deployment)
        </Step>
      </Steps>
    </div>
  </Card>
</Panel>

<Check>
  **What you'll learn in this lesson:**

  * Diagnose slug mismatch errors between event types and models
  * Fix timing and sequencing issues in batch generation
  * Resolve data type mismatches and unit conversion errors
  * Troubleshoot calculation dependency problems
</Check>

Even with careful configuration, integration issues arise when connecting the pieces of a production accounting project. This lesson covers the most common pitfalls and how to fix them.

## Pitfall 1: Slug mismatches

The **most common** integration error. It happens when the datapoint slug in the event type doesn't match what the model expects.

<AccordionGroup>
  <Accordion defaultOpen="true" icon="triangle-exclamation" title="Symptoms">
    * Model node produces no output (empty/null value)
    * Batch generation validation says "missing required datapoint"
    * Some batches have outputs, others don't (inconsistent slug across events)
  </Accordion>

  <Accordion icon="magnifying-glass" title="Diagnosis">
    1. Open the <a href="/production-accounting/models" target="_blank" rel="noopener noreferrer">Model Editor</a>

       and note the `data_point_type` slug for each input node
    2. Open **Data Inputs > Input Settings** and check the actual slug for each datapoint in the event type
    3. Compare — they must be **exactly** identical (case-sensitive, hyphens vs. underscores)
  </Accordion>

  <Accordion icon="wrench" title="Fix">
    Update either the model node's `data_point_type` or the event type's datapoint slug so they match. If you change the event type slug, existing events may need to be updated.

    <Tip>
      Establish a slug naming convention early (e.g., always use hyphens, always lowercase) and stick to it. This prevents mismatches before they happen.
    </Tip>
  </Accordion>
</AccordionGroup>

## Pitfall 2: Timing and sequencing issues

Events must fall within the accounting period for their data to be included in a batch.

<AccordionGroup>
  <Accordion defaultOpen="true" icon="triangle-exclamation" title="Symptoms">
    * Batch shows zero output even though events exist
    * Some events are included in the batch but others aren't
    * Validation passes but output is unexpectedly low
  </Accordion>

  <Accordion icon="magnifying-glass" title="Diagnosis">
    1. Check the **date range** of your events vs. the batch accounting period
    2. Verify the event's `start_time` and `end_time` — do they overlap with the batch period?
    3. Look at the **show time** option when generating batches — time-of-day can exclude events at period boundaries

    Per the <a href="/production-accounting/generate-batches" target="_blank" rel="noopener noreferrer">Generate Batches</a>

    documentation, events must fall within the selected accounting period.
  </Accordion>

  <Accordion icon="wrench" title="Fix">
    * Adjust event date ranges to fall within the accounting period
    * Use the **show time** option to include events at period boundaries
    * For monthly data (like energy consumption), ensure the event date range covers the full month

    <Warning>
      A common mistake: creating an energy consumption event with a single date instead of a date range. If the event covers January 1-31, set both start\_time and end\_time accordingly.
    </Warning>
  </Accordion>
</AccordionGroup>

## Pitfall 3: Data type mismatches

A numeric datapoint stored as text, or a percentage stored as a decimal when the model expects a whole number.

<AccordionGroup>
  <Accordion defaultOpen="true" icon="triangle-exclamation" title="Symptoms">
    * Calculation produces wildly incorrect values (e.g., 8000% instead of 80%)
    * Type errors in the model console
    * Values appear correct in events but produce wrong model outputs
  </Accordion>

  <Accordion icon="magnifying-glass" title="Diagnosis">
    1. Check the **value type** configured for each datapoint in the event type (number, text, date)
    2. Check how the model interprets the value — does it expect a fraction (0.80) or a percentage (80)?
    3. Look at actual event values — are they stored as the correct type?
  </Accordion>

  <Accordion icon="wrench" title="Fix">
    * If the model expects a fraction but events store percentages, add a division-by-100 node in the model
    * Ensure all numeric datapoints are configured as `number` type (not `text`)
    * Add explicit unit conversion nodes rather than assuming units match

    <Note>
      The most common data type issue is **percentages**: an event stores `80` (meaning 80%) but the model multiplies directly by `80` instead of `0.80`. Always add an explicit division by 100 for percentage datapoints.
    </Note>
  </Accordion>
</AccordionGroup>

## Pitfall 4: Calculation dependency problems

A model node that depends on another node's output but the dependency isn't correctly wired.

<AccordionGroup>
  <Accordion defaultOpen="true" icon="triangle-exclamation" title="Symptoms">
    * Model validation error about circular dependencies
    * Intermediate node shows correct value but downstream node doesn't use it
    * Output is always the same regardless of input changes
  </Accordion>

  <Accordion icon="magnifying-glass" title="Diagnosis">
    1. In the Model Editor, trace the node tree from output back to inputs
    2. Verify each calculated node's children are correctly listed
    3. Check that intermediate nodes are referenced by name (not recreated)
    4. Look for nodes with no children or orphaned nodes not connected to the tree
  </Accordion>

  <Accordion icon="wrench" title="Fix">
    * Ensure each calculated node explicitly lists its children in the YAML
    * Remove any duplicate nodes — each calculation should exist once and be referenced by downstream nodes
    * If you see circular dependency errors, restructure the tree so data flows in one direction

    <Tip>
      Draw the node tree on paper first. It should be a directed acyclic graph (DAG) — every path goes from inputs to outputs, never backwards.
    </Tip>
  </Accordion>
</AccordionGroup>

## Pitfall 5: Missing aggregation across events

When a model expects aggregated values (e.g., total kWh for the month) but receives individual event values.

<AccordionGroup>
  <Accordion icon="triangle-exclamation" title="Symptoms">
    * Emission calculations use only one energy event instead of the sum
    * Batch output changes depending on which event is processed first
    * Total emissions don't match the sum of all energy events
  </Accordion>

  <Accordion icon="magnifying-glass" title="Diagnosis">
    Check whether the model node has the `should_aggregate` flag set. Without it, the node may only pick up a single event's value rather than summing across all events of that type in the period.
  </Accordion>

  <Accordion icon="wrench" title="Fix">
    Set `should_aggregate: true` on model input nodes that need to sum values across multiple events (e.g., total electricity for the month). See the <a href="/production-accounting/models" target="_blank" rel="noopener noreferrer">model reference</a>

    for aggregation options.
  </Accordion>
</AccordionGroup>

## Debugging workflow

When something goes wrong, follow this systematic approach:

```mermaid theme={null}
flowchart TB
    START["Output doesn't<br/>match expected"] --> EVENTS{"Events<br/>correct?"}
    EVENTS -->|No| FIX_E["Fix event<br/>data/dates"]
    EVENTS -->|Yes| MODEL{"Model nodes<br/>correct?"}
    MODEL -->|No| FIX_M["Fix slugs,<br/>operators,<br/>dependencies"]
    MODEL -->|Yes| BATCH{"Batch config<br/>correct?"}
    BATCH -->|No| FIX_B["Fix partition<br/>cadence,<br/>output types"]
    BATCH -->|Yes| LEDGER{"Ledger<br/>balances?"}
    LEDGER -->|No| FIX_L["Fix allocation<br/>rules"]
    LEDGER -->|Yes| RECHECK["Re-check<br/>expected values"]

    style START fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
    style EVENTS fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style MODEL fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style BATCH fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
    style LEDGER fill:#ab47bc,stroke:#7b1fa2,stroke-width:2px,color:#000
    style FIX_E fill:#ffa726,stroke:#f57c00,stroke-width:2px,color:#000
    style FIX_M fill:#ffa726,stroke:#f57c00,stroke-width:2px,color:#000
    style FIX_B fill:#ffa726,stroke:#f57c00,stroke-width:2px,color:#000
    style FIX_L fill:#ffa726,stroke:#f57c00,stroke-width:2px,color:#000
    style RECHECK fill:#78909c,stroke:#455a64,stroke-width:2px,color:#000
```

***

### Check your understanding

<Accordion icon="circle-question" title="What is the most common integration error and how do you diagnose it?">
  **Slug mismatches** between event type datapoints and model nodes. Diagnose by comparing the `data_point_type` in the Model Editor against the actual slug in Data Inputs > Input Settings. They must be exactly identical — case-sensitive, same delimiters (hyphens vs. underscores).
</Accordion>

<Accordion icon="circle-question" title="How do you fix the 'percentage vs. fraction' data type issue?">
  Add an explicit **division-by-100 intermediate node** in the model. If the event stores `80` (meaning 80%), the model should include a node that divides by 100 to get `0.80` before using it in multiplication. Never assume input units — make conversions explicit and visible.
</Accordion>

***

You're ready to put all of this into practice in the [Module 5 Exercise: End-to-End Integration Testing](/accounting-academy/module-5/5-exercise-integration-testing).