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

# Troubleshooting

First step for almost everything: `Config.debug = true`, restart, reproduce, watch the server console for `[awoken_spawn]` lines.

## Selector doesn't open

Look for `[awoken_spawn] open src=X isNew=Y -> N cards`.

* **Line missing** → nothing triggered the open.
  * Confirm `Config.open.autoOpenOnFrameworkLoad = true`.
  * Confirm your framework fires one of the events listed in [Installation](installation.mdx).
  * If you're using a standalone multichar, verify it either fires the framework's normal player-loaded event, or is listed in `Config.open.multichar`, or calls `awoken_spawn:server:requestOpen`.
* **Line present, no UI on the client** → check F8 console for JS errors. After a Vite rebuild, the asset hash filenames in `html/index.html` need to match what's actually in `html/build/`.

## `/spawnselect` says "Unknown command"

Only registered when `Config.debug = true`. Flip and restart.

## Character visible during selection

`Config.open.hideCharacter = true` (default) hides the ped. If something downstream is fighting it, wrap that resource's visibility writes to skip while the selector is open.

## PVP doesn't work after spawning

Quick test in F8 after a spawn:

```
NetworkSetFriendlyFireOption(true)
SetEntityInvincible(PlayerPedId(), false)
SetEntityCanBeDamaged(PlayerPedId(), true)
```

If PVP works after that, something downstream is re-disabling it. Find that resource. Confirm `Config.spawn.setPvpDefault = true`.

## Pins misaligned

Set `Config.debug = true` and use the calibration wizard in the top-right badge (single-click to pick pin coords, or run the two-point wizard for a full `worldBounds` block). See the [Map](map.mdx) page.

## Last location doesn't persist

* Confirm `Config.database.enabled = true`.
* Confirm `oxmysql` is ensured **before** `awoken_spawn`.
* Check the DB — the table (default `awoken_spawn_lastchoice`) is auto-created on first run.

## The Last Location card isn't showing at all

This is deliberate when there is nowhere real to send the player. The card used
to appear regardless and silently spawn them at `Config.spawn.fallbackCoords`,
which looked like "last location is broken" rather than "there is no last
location".

The card is offered when **any** of these resolve, in order:

1. a position handed over by the multicharacter script
2. a usable `coords` value in `awoken_spawn_lastchoice`
3. the framework's own saved position (`players.position` on QB/QBX, the
   `users` row on ESX) — controlled by `Config.database.frameworkFallback`

The server log names which one was used, or says nothing was usable. A row with
a NULL `coords` column is normal and not corruption: it is what a housing
handoff writes, because the housing script owns the placement.

## I picked my property but spawned somewhere else

The housing script did not react to the handoff. Look for this in the client console:

```
housing handoff for "property:..." fired but the player never moved
```

That means the event or export we call for that housing resource is wrong for
your version. The player is dropped at normal coords instead of being left
stranded, so it degrades rather than breaks. Send that line over and the branch
in `client/spawn.lua` can be corrected.

## New character gets stuck on a black screen

Fixed in the current build, but the symptom to recognise is a black screen after
character creation with the selector's text visible, plus this in the server console:

```
[awoken_spawn:OPEN] bailed: already pending for src=N
```

The framework-load hook and the multicharacter handoff were both trying to open
the selector, and the first one to arrive blocked the second. When a
multicharacter script is detected, the framework hook now stands down and logs:

```
[awoken_spawn:BOOT] <multichar> detected — not hooking framework load
```

If you see the "already pending" line without the "not hooking" line, the
multicharacter resource is not being detected — check its folder name against
the list in `multicharPresent()`.

## Housing property card missing

* Confirm the housing resource is in `Config.housing.detect`.
* Confirm the player actually owns something in that resource's DB.
* Order matters — the first available adapter that returns properties wins the handoff.

## Discord not posting

* `Config.discord.webhook` is empty (`''`) by default — off. Set the URL to enable.
* Posts are non-blocking, so a bad webhook won't break spawns — it'll silently no-op.

## "Resource must be named awoken\_spawn"

The folder is named something else. Rename it back.

## "oxmysql tried to call a function reference in X but X isn't started"

Not us — the error message names the actual broken resource. Fix or remove that one.