# Error Reference & Diagnostics

This page maps common Nord Inventory messages and integration return codes to their likely cause.

# User-facing external-use errors

| Message | Meaning | What to check |
|---|---|---|
| `Invalid inventory request.` | Generic fallback for an unmapped/invalid action | First related console error, stale definition, slot/session validity |
| `External use export configuration is invalid.` | Nord could not normalize the external export descriptor | Resource/export/side fields |
| `External resource "X" is not started.` | Target resource state is not `started` | `ensure` order, resource folder name, startup failure |
| `External export X:Y failed.` | The called export threw an error | Target resource console stack trace |
| `External export X:Y rejected the item use.` | Export explicitly returned `false` | Resource validation logic |
| `The item use handler failed.` | Registered Lua callback errored | Server stack trace in registering resource |
| `The item use request expired.` | Pending use token timed out before completion | frozen client/progress flow, delayed callback, stale event |
| `The definition for this item is not available.` | Definition missing or disabled | DB/reference/runtime registry ownership |

# Registration return codes

## `database_authoritative`

A runtime `RegisterItem` attempted to use a name already owned by `nord_inventory_custom_items`.

**Correct fix:** keep the database item and attach only its runtime handler with `RegisterUseExport` / `RegisterUsableItem`, or deliberately remove/revert the DB definition if the external resource should own it.

## `reference_disabled`

An administrator disabled the reference/base item. Runtime registration is not allowed to silently reactivate it.

**Correct fix:** restore the item from Admin Studio if it should be active again.

## `invalid_export`

The handler string/table cannot be normalized into a valid external export descriptor.

Check:

```text
resource name
export name
side = client | server
```

## `invalid_items`

`RegisterItems` did not receive a table.

## `invalid_item` / `invalid_name`

The requested item name is empty or fails Nord's item-name sanitization.

## `invalid_inventory`

An integration export could not resolve the requested inventory target.

# FiveM funcref error

```text
SCRIPT ERROR: @nord_inventory/shared/utils.lua:...: Cannot index a funcref
```

Nord Inventory handles Cfx function references safely. If this appears, assume a **mixed/partial update** first.

Recommended recovery:

```text
stop nord_carplay # or the registering resource
stop nord_inventory
replace the complete nord_inventory folder
start nord_inventory
start nord_carplay
```

# CarPlay-specific rejection

Wrong configuration:

```text
Resource: nord_carplay
Export: UseCarplay
Execution side: Server
```

for the documented client installation flow.

Correct Admin Studio configuration:

```text
Resource: nord_carplay
Export: carplay
Execution side: Client
Remove on use: Off
```

The CarPlay server removes the item only after installation succeeds.

# Diagnostic rule

Always fix the **first** relevant stack trace or specific external-use notification before the generic `Invalid inventory request.` message. Generic fallback messages are often consequences, not the original cause.