# 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.