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

# Troubleshooting

> Common issues and how to fix them.

## Resource won't start

```
[awoken_apartments] STARTUP BLOCKED - resource must be named awoken_apartments
```

The folder was renamed. Restore the original name: `awoken_apartments` (with underscore, not hyphen).

## Client error: `attempt to index a nil value (field 'Apartments')`

```
SCRIPT ERROR: @awoken_apartments/client/main.lua: attempt to index a nil value (field 'Apartments')
```

The client never loaded `data/apartments.json`. The client reads it with `LoadResourceFile`, which only works if the data files are shipped to the client - i.e. listed in `fxmanifest.lua` under `files {}`. If they're missing, `Config.Apartments` stays `nil` and every apartment lookup (including spawn/auto-enter) errors.

Confirm your `fxmanifest.lua` includes the data files:

```lua theme={"dark"}
files {
    'html/admin.html',
    'html/admin.css',
    'html/admin.js',
    'data/apartments.json',
    'data/motel_groups.json',
    'data/tiers.json',
}
```

After fixing, restart the resource and **fully reconnect** (clients only re-download `files {}` on connect).

## New characters spawn at world default instead of inside their apartment

<Tabs>
  <Tab title="qbox / qbcore">
    Check that qbx\_core sets `PlayerData.newPlayer = true` on character creation. If your multichar is custom, manually trigger client-side after character load:

    ```lua theme={"dark"}
    TriggerEvent('awoken_apartments:newCharacter')
    ```
  </Tab>

  <Tab title="ESX">
    Standard ESX doesn't set a `newPlayer` flag. Either:

    * Add `TriggerEvent('awoken_apartments:newCharacter')` to your character creator after the character is saved
    * Or set `Config.NewCharacterSpawn.enabled = false` and skip the force-spawn feature

    See [Framework setup → New character detection](framework-setup#new-character-detection).
  </Tab>
</Tabs>

## Spawn selector: picking my apartment doesn't teleport me inside

The apartment shows as a choice in your spawn selector, but selecting it leaves you standing at the door (or at the selector's default location) instead of inside.

Cause: the spawn-selector patch is triggering `awoken_apartments:animateEnter` instead of `awoken_apartments:teleportInside`. `animateEnter` gates the teleport behind a key-fob progress bar, which gets interrupted by the selector's spawn fade/camera teardown - so the teleport never fires.

Fix: in your spawn selector's confirm/select handler, call `teleportInside` directly:

```lua theme={"dark"}
-- when the player picks their apartment:
TriggerEvent('awoken_apartments:teleportInside', awokenSlotId)
```

`teleportInside` handles the fade, routing-bucket instance and interior placement itself - no `SetEntityCoords` or `animateEnter` needed. See [Installation → Spawn selector coexistence](installation#spawn-selector-coexistence) for the per-selector patches.

## Stash UI doesn't open

<Tabs>
  <Tab title="qbox / qbcore">
    Verify your inventory matches `Config.Inventory`:

    * `'ox'` → ox\_inventory must be running
    * `'qb'` → qb-inventory must be running
    * `'ps'` → ps-inventory must be running
  </Tab>

  <Tab title="ESX">
    `Config.Inventory = 'esx'` requires `esx_addoninventory` (with or without esx\_inventoryhud). If neither is installed, install `esx_addoninventory` from the legacy ESX repo, or switch to `Config.Inventory = 'ox'` and install ox\_inventory.
  </Tab>
</Tabs>

See [Inventory setup](inventory).

## Player keeps getting a Tier 2 they shouldn't have

Stale billing record. Check:

```sql theme={"dark"}
SELECT * FROM awoken_apartment_billing;
```

Delete the offending row:

```sql theme={"dark"}
DELETE FROM awoken_apartment_billing WHERE identifier = 'THEIR_IDENTIFIER';
```

See [Billing → Manual fixes](billing#manual-fixes).

## Money not deducting on ESX

Check the server console after a transfer/upgrade attempt. You should see:

```
[awoken_apartments:billing] ESX RemoveMoney src=N amount=X source=both newCash=Y newBank=Z
```

If you see this instead:

```
[awoken_apartments:billing] Failed to remove $X cash from src=N
```

…your ESX fork uses a non-standard `xPlayer` API. The resource tries three method variants - if all fail, post your `xPlayer` class and we'll add support.

<Note>
  Most common cause: the player simply doesn't have the money. The billing system checks `Framework.HasMoney` first and aborts if false.
</Note>

## Two apartment systems fighting

Symptoms:

* Two "spawn inside?" prompts
* Player teleports to unexpected location
* Doors with multiple target prompts stacked

Cause: another apartment resource is still running. Stop one of:

* `qb-apartments`
* `qbx_properties` *(or set `startingApartment = false` in qbx\_core to keep qbx\_properties for owned houses only)*
* `esx_apartments`
* `esx_property`
* `loaf_housing`

See [Installation → Disable conflicting resources](installation).

## Door target prompts missing

`Config.Target` doesn't match your installed target script. Set to:

| You have       | `Config.Target`                                          |
| -------------- | -------------------------------------------------------- |
| ox\_target     | `'ox_target'`                                            |
| qb-target      | `'qb_target'`                                            |
| interact-style | `'interact'`                                             |
| None           | `'standalone'` (proximity press-E with native help text) |

## Admin panel `/aptmanager` won't open

Missing ace permission. The panel checks the `apartments.admin` ace - **not** `command.aptmanager`. Add to `server.cfg`:

```cfg theme={"dark"}
add_ace group.admin apartments.admin allow
```

If you're testing as the server owner and have `console` / `group.admin` already, restart your client to re-fetch permissions.

## "No free Tier 1 slots" on new character

You have rooms configured but all Tier 1 ones are taken. Either:

* Add more Tier 1 rooms via `/aptmanager` → Rooms tab → `+ Add Room`
* Convert existing paid-tier rooms back to Tier 1
* Free up slots: `TRUNCATE TABLE awoken_apartment_billing` then restart

## "table index is nil" SQL errors

Caused by the address registry firing for disconnected players. The handler now early-returns when the player's identifier can't be resolved.

If you see new "table index is nil" errors from a different code path, paste the full server stack trace.

## Bucket exploit / players in wrong instances

The server-side `enterInstance` / `enterMlo` handlers validate access on every request - owner check, key holder check, unlocked door check, PD override check. If a request is rejected the server console prints:

```
[awoken_apartments] Rejected enterInstance from N (slot X)
```

If rejections happen but players still end up in the wrong bucket, the problem is somewhere else (manual `SetPlayerRoutingBucket` calls from another resource, for example).

## Resource restart kicks players inside apartments out to the motel exterior

This is intentional - `awoken_apartments:resourceStarted` fires on the client, which fades out and moves the player to the motel exterior so they're not stuck in an empty bucket.

## Debug mode

Set `Config.Debug = true` in [config section 1](configuration#section-1--framework). The server console will print verbose logs on:

* Slot assignments (`Player N assigned apartment slot M`)
* Slot restorations (`Restored billing slot X to player Y from DB`)
* Stash opens (`OPENING → player=N slot=M`)
* Billing actions (`ESX RemoveMoney src=N amount=X`)
* Access rejections (`Rejected enterInstance from N`)

<Warning>
  Disable Debug for production. It spams the console heavily.
</Warning>

## No wardrobe inside the apartment

This is expected - Awoken Apartments doesn't include a wardrobe. Add one using your own clothing script (illenium-appearance, fivem-appearance, qb-clothing, etc.) by placing a target/interaction point at the apartment interior that opens your clothing menu. Step-by-step: [Configuration → Wardrobes & clothing](configuration#wardrobes--clothing).

## Still stuck?

Open a support ticket with:

* Your `Config.Framework` and `Config.Inventory` values
* Server console output (with `Config.Debug = true`)
* F8 console errors
* Steps to reproduce