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

# Operations and troubleshooting

> Check runtime health and resolve common installation, NPC, voice, and provider problems.

Start with the status commands. They expose the supported operational state
without requiring verbose logs.

## Status commands

Run in the server console:

```text theme={null}
humalike_status
humalikenpc:status
```

`humalike_status` reports credential bootstrap and the `player`, `inventory`,
`dispatch`, and `actions` provider domains. `humalikenpc:status` reports the
selected player provider, roster size, and latest roster synchronization.

Run `humalike_status` in the client F8 console to inspect the interaction
provider. Run `/voice` to inspect the local voice connection.

`humalikenpc:reload` requests an immediate roster refresh. The server and client
commands are ACE-restricted where FiveM command permissions apply.

## Provider states

| State         | Meaning                                      | Action                                           |
| ------------- | -------------------------------------------- | ------------------------------------------------ |
| `selected`    | One available provider is active.            | None.                                            |
| `disabled`    | The domain is configured as `none`.          | Enable it only if the feature is required.       |
| `unavailable` | No provider matches the setting.             | Start its dependency or fix the configured name. |
| `ambiguous`   | Top available providers have equal priority. | Select one explicitly.                           |
| `degraded`    | A selected provider callback failed.         | Inspect that bridge or dependency.               |

## Temporary debug logging

```cfg theme={null}
setr humalike_debug 1
```

Restart the resource, reproduce one issue, collect the relevant lines, then set
it back to `0`. Debug mode is intentionally noisy and should not remain enabled
on a busy production server.

Remove credentials and signed connection URLs before sharing logs.

## Resource does not become ready

Check, in order:

1. `humalike_license_key` uses `set`, contains the current server license, and
   appears before `ensure humalike`.
2. The registered callback URL contains this FXServer's globally routable
   literal public IPv4 address.
3. Inbound TCP traffic reaches that port.
4. The server registration is enabled.
5. The FXServer build is current and OneSync is enabled.

Rotate the license only if it is lost or exposed; rotation invalidates the old
value immediately.

## NPC is missing

* Confirm that the server status is ready and the roster count is non-zero.
* Confirm that the NPC and server are enabled in the dashboard.
* For static NPCs, verify model, coordinates, heading, routing bucket, and map
  geometry.
* For ambient NPCs, verify that ambient policy is enabled and that compatible
  GTA population models exist nearby.
* Run `humalikenpc:reload` once instead of repeatedly restarting the server.

## NPC does not answer

* Verify the player's microphone and HumaLike PTT binding.
* Use `/voice` and check that the intended NPC is not muted for that player.
* Move close and face the NPC for a direct conversation.
* Check the server's available [NPC turns](/npc-turns).
* Confirm that the NPC has a voice and is enabled.

An NPC can also choose not to speak based on its character and current
conversation. Test multiple clear utterances before treating silence as a
connection failure.

## `/me` or `/do` is ignored

Built-in integration depends on the framework's supported roleplay event. A
custom chat resource may display the command without publishing that event. In
that case, call `ReportPlayerEvent` from the chat resource's server handler. See
[Report player events](/ai-npc/integrations/world-events).

## Inventory action is unavailable

Run `humalike_status` and check the `inventory` domain. `give_item` is advertised
only while an inventory provider is selected. Resolve an unavailable or
ambiguous provider, then allow HumaLike to refresh its capabilities.

## NUI callback or asset errors after an update

Mixed releases are the common cause. Stop HumaLike, replace the entire resource
directory with the contents of one `humalike.zip`, and start it again. Do not
overlay releases or copy only the compiled web files.

## Reporting a bug

Include the HumaLike release version, FXServer artifact version, framework and
provider status, exact reproduction steps, and sanitized logs. Report security
issues through [private vulnerability reporting](https://github.com/Humalike/humalike-fivem-npc/security/advisories/new).

## Next

* [Look up public commands and exports](/ai-npc/reference).
* [Review security guidance](/ai-npc/security).
* [Open the AI NPC dashboard](https://humalike.ai/ai-npc).