# Build Error Quick Reference

**Purpose:** Instant lookup for common build errors with solutions and links to detailed guides.

**Last Updated:** 2026-07-01

---

## How to Use This Guide

1. **Find your error message** in the tables below
2. **Apply the quick fix** for immediate resolution
3. **Read the detailed guide** for understanding and prevention

---

## Error Index by Category

-   [JSDoc / Business Logic Errors](#jsdoc--business-logic-errors)
-   [UI Structure Errors](#ui-structure-errors)
-   [Process Flow Errors](#process-flow-errors)
-   [DataSource Errors](#datasource-errors)
-   [Locale / Label Errors](#locale--label-errors)

---

## JSDoc / Business Logic Errors

| Error Message Pattern                                                      | Root Cause                                           | Quick Fix                                         | Detailed Guide                                                                                     |
| -------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `Cannot read properties of undefined (reading 'name')`                     | Missing or incomplete JSDoc tags                     | Add complete JSDoc header with all mandatory tags | [JSDoc Tags - Build Errors](../skills/create-business-logic/references/jsdoc-tags.md#build-errors) |
| `method not found`                                                         | @function name doesn't match filename or JS function | Sync @function, JS function name, and filename    | [JSDoc Tags](../skills/create-business-logic/references/jsdoc-tags.md#function-name)               |
| `The customizing javaScript start tag required in the function is missing` | Missing comment blocks around code                   | Add `//// Add your customizing...` comment blocks | [Business Logic](../skills/create-business-logic/SKILL.md)                                         |

### Quick Fix Example: JSDoc

```javascript
✅ CORRECT Structure:

"use strict";

[... auto-generated header ...]

/**
 * @function createTestData
 * @this LoProductName
 * @kind listobject
 * @namespace CUSTOM
 */
function createTestData(){
    var me = this;
    ///////////////////////////////////////////////////////////////////////////////////////////////
    //               Add your customizing javaScript code below.                                 //
    ///////////////////////////////////////////////////////////////////////////////////////////////

    // Your code here

    ///////////////////////////////////////////////////////////////////////////////////////////////
    //               Add your customizing javaScript code above.                                 //
    ///////////////////////////////////////////////////////////////////////////////////////////////


}
```

---

## UI Structure Errors

| Error Message Pattern                                                                                | Root Cause                                      | Quick Fix                                                                   | Detailed Guide                                                                                                                      |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Element 'DataGrid': This element is not expected`                                                   | DataGrid used without FastDataEntryGrid wrapper | Wrap in FastDataEntryGrid with complete structure                           | [UI Control Dependencies - Pattern 1](../patterns/ui-control-dependencies.md#pattern-1-fastdataentrygrid-complex-composite-control) |
| `Element 'Label': This element is not expected`                                                      | Label used as standalone element                | Use as Resource binding target in parent control                            | [UI Control Dependencies - Pattern 2](../patterns/ui-control-dependencies.md#pattern-2-label-and-image-binding-targets-only)        |
| `Element 'Image': This element is not expected`                                                      | Image used as standalone element                | Use as Resource binding target in parent control                            | [UI Control Dependencies - Pattern 2](../patterns/ui-control-dependencies.md#pattern-2-label-and-image-binding-targets-only)        |
| `Element 'ImageButton': This element is not expected`                                                | ImageButton in wrong container                  | Move to ButtonGridArea, LinkBar, or ActionBar                               | [UI Control Dependencies - Pattern 3](../patterns/ui-control-dependencies.md#pattern-3-imagebutton-container-restrictions)          |
| `Element 'FastDataEntryGrid': Missing child element(s). Expected is ( DataInputArea )`               | FastDataEntryGrid without DataInputArea         | Add complete DataInputArea with DataSearchField + NumberInputField + Events | [UI Control Dependencies - Pattern 1](../patterns/ui-control-dependencies.md#pattern-1-fastdataentrygrid-complex-composite-control) |
| `Element 'DataInputArea': Missing child element(s). Expected is one of ( NumberInputField, Events )` | Incomplete DataInputArea structure              | Add all required children: DataSearchField, NumberInputField, Events        | [UI Control Dependencies - Pattern 1](../patterns/ui-control-dependencies.md#pattern-1-fastdataentrygrid-complex-composite-control) |

### Quick Fix Example: DataGrid

```xml
❌ WRONG:
<Area areaName="mainArea" areaPattern="SingleElementArea">
  <DataGrid name="ProductGrid" ...>  <!-- Error: not expected -->
  </DataGrid>
</Area>

✅ CORRECT:
<Area areaName="mainArea" areaPattern="SingleElementArea">
  <FastDataEntryGrid name="ProductEntry">
    <DataInputArea name="ProductInput">
      <DataSearchField name="ProductSearch" ...>
        ...
      </DataSearchField>
      <NumberInputField name="quantityInput" ...>
        ...
      </NumberInputField>
      <Events>
        <CreateNewRecordEvent event="AddItem">
          ...
        </CreateNewRecordEvent>
      </Events>
    </DataInputArea>
    <DataGrid name="ProductGrid" ...>
      ...
    </DataGrid>
  </FastDataEntryGrid>
</Area>
```

---

## Process Flow Errors

| Error Message Pattern                                                  | Root Cause                                            | Quick Fix                                                   | Detailed Guide                                                                                                              |
| ---------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Element 'TransitionTo': This element is not expected` in EntryActions | TransitionTo not allowed in EntryActions              | Remove TransitionTo - automatic transition to defaultAction | [Process Action Types - EntryActions Rules](../skills/create-process/references/action-types.md#entryactions-special-rules) |
| `Element 'Return': This element is not expected`                       | Return element in wrong location or wrong action type | Check action type supports Return, verify element order     | [Process Action Types](../skills/create-process/references/action-types.md)                                                 |
| `Attribute 'object' is not allowed` in LOAD action                     | Old syntax not supported                              | Remove object attribute from LOAD action                    | [Create Process](../skills/create-process/SKILL.md)                                                                         |

### Quick Fix Example: EntryActions

```xml
❌ WRONG:
<EntryActions>
  <Action actionType="LOGIC" name="LoadData" call="ProcessContext::loItems.createTestData">
    <TransitionTo action="ShowView" />  <!-- Error: not expected -->
  </Action>
</EntryActions>

✅ CORRECT:
<EntryActions>
  <Action actionType="LOGIC" name="LoadData" call="ProcessContext::loItems.createTestData" />
  <!-- Automatically transitions to defaultAction -->
</EntryActions>
```

---

## DataSource Errors

| Error Message Pattern                                                                             | Root Cause                 | Quick Fix                                                   | Detailed Guide                                            |
| ------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------- |
| `Element 'DataSource', attribute 'dataSourceType': The attribute 'dataSourceType' is not allowed` | Wrong DataSource syntax    | Use backendSystem, objectClass, businessObjectClass instead | [DataSource Patterns](../patterns/datasource-patterns.md) |
| `Element 'DataSource', attribute 'type': The attribute 'type' is not allowed`                     | Wrong DataSource syntax    | Remove type attribute                                       | [DataSource Patterns](../patterns/datasource-patterns.md) |
| `Element 'Columns': This element is not expected`                                                 | Wrong DataSource schema    | Use Attributes/Entities instead of Columns                  | [Create DataSource](../skills/create-datasource/SKILL.md) |
| `Attribute 'businessObjectClass' is missing`                                                      | Required attribute missing | Add businessObjectClass="[LoName                            | BoName]"                                                  | [Create DataSource](../skills/create-datasource/SKILL.md) |

### Quick Fix Example: DataSource

```xml
❌ WRONG (Old syntax with Columns):
<DataSource dataSourceType="Table" name="DsLoProducts" type="NamedQuery">
  <Columns>
    <Column name="pKey" type="DomPKey" />
  </Columns>
</DataSource>

✅ CORRECT (Declarative pattern - preferred):
<DataSource name="DsLoProducts" backendSystem="sf"
            businessObjectClass="LoProducts"
            external="false" editableEntity="Product__c" schemaVersion="2.0">
  <Attributes>
    <Attribute name="pKey" table="Product__c" column="Id" />
    <Attribute name="productNumber" table="Product__c" column="Product_Number__c" />
    <Attribute name="productName" table="Product__c" column="Name" />
    <Attribute name="category" table="Product__c" column="Category__c" />
    <Attribute name="quantity" table="Product__c" column="Quantity__c" />
    <Attribute name="price" table="Product__c" column="Price__c" />
  </Attributes>
  <Entities>
    <Entity name="Product__c" alias="" idAttribute="Id" />
  </Entities>
  <QueryCondition />
  <OrderCriteria />
  <Parameters />
</DataSource>
```

---

## Locale / Label Errors

| Error Message Pattern                                         | Root Cause                                   | Quick Fix                                         | Detailed Guide                                                              |
| ------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- |
| `Element '[CustomSectionName]': This element is not expected` | Custom locale section not allowed            | Add labels to UserInterfaceContracts section only | [Locale Label Resolution](locale-label-resolution.md#important-rules)       |
| `Element 'Label': This element is not expected` after section | Labels placed outside UserInterfaceContracts | Move labels inside UserInterfaceContracts section | [Locale Label Resolution](locale-label-resolution.md#locale-file-structure) |

### Quick Fix Example: Locale

```xml
❌ WRONG:
<Locale language="en">
  <Translations>
    <Framework>
      <!-- READ-ONLY - Don't add labels here -->
    </Framework>
    <Label id="NewId" text="New" />  <!-- Error: not in UserInterfaceContracts -->
  </Translations>
</Locale>

✅ CORRECT:
<Locale language="en">
  <Translations>
    <Framework>
      <!-- READ-ONLY - Don't touch -->
    </Framework>
    <UserInterfaceContracts>
      <UserInterface id="MyModule_DetailUI">
        <Label id="NewId" text="New" translationStatus="7"/>
      </UserInterface>
    </UserInterfaceContracts>
  </Translations>
</Locale>
```

---

## Troubleshooting Workflow

### Step 1: Identify Error Category

```
Build failed?
│
├─ Error message contains "JSDoc" or "js2json"?
│  └─ → JSDoc / Business Logic Errors section above
│
├─ Error message contains "Element" and control name?
│  └─ → UI Structure Errors section above
│
├─ Error message contains "TransitionTo" or action type?
│  └─ → Process Flow Errors section above
│
├─ Error message contains "DataSource" or "Attribute"?
│  └─ → DataSource Errors section above
│
└─ Error message contains "Label" or "Locale"?
   └─ → Locale / Label Errors section above
```

### Step 2: Apply Quick Fix

Use the quick fix from the table to resolve immediately.

### Step 3: Read Detailed Guide

Follow the "Detailed Guide" link to:

-   Understand why the error occurred
-   Learn how to prevent it in future
-   See complete working examples

### Step 4: Verify Fix

```bash
sf mdl build
```

If new errors appear, repeat from Step 1.

---

## Common Error Combinations

### Combination 1: DataGrid + JSDoc + Locale

**Scenario:** Implementing DataGrid for first time

**Likely Errors:**

1. `Element 'DataGrid': This element is not expected`
2. `Cannot read properties of undefined (reading 'name')`
3. Labels show as raw IDs

**Solution Path:**

1. Fix DataGrid structure → [UI Control Dependencies](../patterns/ui-control-dependencies.md#pattern-1-fastdataentrygrid-complex-composite-control)
2. Fix JSDoc in createTestData → [JSDoc Tags](../skills/create-business-logic/references/jsdoc-tags.md#build-errors)
3. Add labels to locale → [Locale Label Resolution](locale-label-resolution.md)

### Combination 2: Process + EntryActions + LOGIC

**Scenario:** Setting up Process initialization

**Likely Errors:**

1. `Element 'TransitionTo': This element is not expected`
2. `Cannot read properties of undefined (reading 'name')`

**Solution Path:**

1. Remove TransitionTo from EntryActions → [Process Action Types](../skills/create-process/references/action-types.md#entryactions-special-rules)
2. Fix JSDoc in BL method → [JSDoc Tags](../skills/create-business-logic/references/jsdoc-tags.md)

---

## Prevention Strategies

### Before You Build

1. **Check production examples** for rare/complex controls
2. **Verify JSDoc completeness** in all .bl.js files
3. **Validate label IDs exist** in locale files
4. **Review structural dependencies** for complex controls

### During Development

1. **Build frequently** (after each major change)
2. **Read error messages completely** (they tell you what's expected)
3. **Fix one error at a time** (don't make multiple changes between builds)
4. **Keep this reference open** for quick lookups

### After Build Errors

1. **Don't guess at fixes** - use this reference
2. **Read detailed guides** to understand root cause
3. **Document new patterns** you discover
4. **Share solutions** with team

---

## Related Documentation

-   [UI Control Dependencies](../patterns/ui-control-dependencies.md) - Structural patterns
-   [Create Business Logic](../skills/create-business-logic/SKILL.md) - BL fundamentals
-   [Create Process](../skills/create-process/SKILL.md) - Process patterns
-   [Locale Label Resolution](locale-label-resolution.md) - i18n patterns
-   [Build and Simulate](../skills/build-and-simulate/SKILL.md) - Build system guide

---

**Pro Tip:** Bookmark this page for instant access during development. Most build errors can be resolved in < 5 minutes with the right reference.