# Common `sf mdl build` and `sf mdl simulate` errors

## Build-time errors (caught by `sf mdl build`)

### `DataSource not found: Ds<Name>`

**Cause:** A BO/LO references a DataSource name that doesn't exist or has a typo.
**Fix:** Grep for the name in `src/` — confirm the file exists and the `name=""` attribute matches exactly.

### `Entity <X> not found`

**Cause:** DS references a table name not known to the modeler's entity registry.
**Fix:** Run the `verify-sqlite-schema` skill — the table is likely absent from `app.db3`.

### `Duplicate name: <X>`

**Cause:** Two files declare the same `name=""` attribute.
**Fix:** `grep -rn 'name="<X>"' src/` to find both; rename one.

### Missing `@namespace CUSTOM` in a new `.bl.js`

**Cause:** A new business-logic file lacks the `@namespace CUSTOM` JSDoc declaration and compiles into the CORE namespace.
**Fix:** Add `@namespace CUSTOM` to the JSDoc block per `_shared/namespace.md`. (XML contracts do not use this directive.)

## Runtime errors (only caught by `sf mdl simulate` or on-device testing)

### `SQLITE_ERROR: no such column: <col>`

**Cause:** DS declares a column that isn't in the local SQLite schema. Build passes because the modeler doesn't validate against runtime DB.
**Fix:** Invoke `verify-sqlite-schema`.

### `SQLITE_ERROR: no such table: <table>`

**Cause:** DS reads a table not present in `app.db3`.
**Fix:** Invoke `verify-sqlite-schema`.

### `Cannot read properties of undefined (reading 'Load')`

**Cause:** DS has `external="false"` but also has a `<Database><Load>` block, or has `external="true"` with `<QueryCondition>` instead.
**Fix:** Match `external` attribute to DS content per `create-datasource` skill.

### `Uncaught TypeError: X is not a function` in console

**Cause:** Typo in `.bl.js` method name that a process or UI tries to call.
**Fix:** Grep the method name across `src/`; ensure spelling matches the caller.

## How to diagnose a crash

1. Open the simulator's dev-tools console (F12 in Chromium-based runners).
2. Reproduce the crash.
3. Read the top of the stack — first `src/`-file reference is the one to inspect.
4. If the error is SQLite-related, the DS is the place to fix it.
5. If the error is "undefined", it's either a missing BL method or a wrong DS `external` attribute.

## Log files

`sf mdl simulate` writes runtime logs to `<log-dir>/`. Confirm the exact path by running:

```bash
find <workspace> -name "*.log" -newer /tmp 2>/dev/null | head
```