> For the complete documentation index, see [llms.txt](https://zynoxdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zynoxdev.gitbook.io/docs/zynox-resources/zx_nameguard/troubleshooting.md).

# Troubleshooting & FAQ

Zynox Studio Documents > ZYNOX RESOURCES > 🛡️ ZX - Name Guard

## ❓ Troubleshooting & FAQ

Solutions for common setup questions, queue compatibility, and database matching with ZX Name Guard

***

### 🛠️ Common Issues & Fixes

#### 1. Stuck on "Connecting... Verifying player name synchronization..."

* **Symptoms:** The connection screen opens, the Adaptive Card flashes or doesn't appear, and the player gets stuck on the loading dialog:

  ```
  Connecting...
  zx_nameGuard: [ZynoxDev] Verifying player name synchronization...
  [Cancel]
  ```
* **Cause:** Your server is running a standalone queue script (such as `connectqueue`). In FiveM, `connectqueue` runs an internal loop that repeatedly calls `deferrals.update(...)`. When another resource presents an Adaptive Card, FiveM immediately closes the card whenever `deferrals.update` is invoked. Because the player cannot click the "Disconnect" button on the closed card, the connection stays deferred.
* **Fix:**
  1. Open `config.lua`.
  2. Change `Config.RejectStyle` from `'adaptive_card'` to `'text_message'`:

     ```lua
     Config.RejectStyle = 'text_message'
     ```
  3. Save and restart `zx_nameGuard`. *(Text mode calls `deferrals.done(rejectReason)` instantly, rejecting the player with a cleanly formatted modal before `connectqueue` can interfere).*

***

#### 2. ESX Players Join the Server but Get Warned In-Game

* **Symptoms:** An ESX player connects with an incorrect name, is allowed to join through the queue, but upon spawning into the game the warning menu appears.
* **Cause:** ESX servers using `esx_multicharacter` store identifiers with prefixes such as `char1:license:xxxx` or `char2:xxxx` instead of raw licenses. Standard SQL queries searching for `license:xxxx` find 0 rows, leading the queue guard to assume the player is brand new.
* **Fix:**
  * `zx_nameGuard` has a built-in multi-slot scanner and `LIKE '%license%'` matcher that handles `char1:` through `char10:` automatically.
  * Ensure you are running the latest version of `server/main.lua`.
  * If you forced `Config.Framework = 'esx'`, ensure `es_extended` has started in your `server.cfg` before `zx_nameGuard`.

***

#### 3. Discord Webhook Logs Not Appearing

* **Symptoms:** Rejections and warnings happen in-game, but nothing shows up in your Discord channel.
* **Checklist:**
  1. **Check `Config.Discord.Enabled`:** Ensure it is set to `true`:

     ```lua
     Config.Discord.Enabled = true
     ```
  2. **Validate the Webhook URL:** Ensure you haven't left the default placeholder text. The URL must start with `https://discord.com/api/webhooks/...`.
  3. **Channel Permissions:** Ensure the Discord channel has not disabled Webhook integration or restricted incoming bot embeds.
  4. **Discord Rate Limiting:** If multiple tests were fired rapidly within a few seconds, Discord may temporarily rate-limit the webhook. Wait 30 seconds and test again.

***

#### 4. "Table 'database.players' doesn't exist" in Console

* **Symptoms:** An oxmysql error appears in the server console stating that table `players` does not exist.
* **Cause:** You are running an ESX server, but `Config.Framework` was left on `'qb'` or `'auto'` before `es_extended` had started, causing the script to query the QB-Core `players` table instead of the ESX `users` table.
* **Fix:**
  1. Open `config.lua`.
  2. Set `Config.Framework = 'esx'`:

     ```lua
     Config.Framework = 'esx'
     ```
  3. Ensure in `server.cfg` that `ensure es_extended` is placed **above** `ensure zx_nameGuard`.

***

#### 5. Mouse Cursor Stuck on Screen After Closing UI

* **Symptoms:** The in-game NUI window closes, but the mouse cursor remains visible and the player cannot look around.
* **Fix:**
  * Press **Escape** (`ESC`) to trigger the native escape listener.
  * If you modified `web/script.js`, ensure the NUI callback sends `postNUI('close')` so that `client/main.lua` executes:

    ```lua
    SetNuiFocus(false, false)
    ```

***

#### 6. Underscores and Spaces Not Matching

* **Symptoms:** A player named `Kasun_Perera` on FiveM is rejected even though their character name is `Kasun Perera`.
* **Fix:** Ensure `Config.AllowUnderscoreAsSpace` is set to `true` in `config.lua`:

  ```lua
  Config.AllowUnderscoreAsSpace = true
  ```

  This automatically converts underscores `_` to spaces during string normalization.

***

### 🙋 Frequently Asked Questions (FAQ)

<details>

<summary><strong>Does this script require manual database table imports?</strong></summary>

**No.** `zx_nameGuard` dynamically inspects and queries your existing framework tables (`players` for Qbox/QB, `users` for ESX). Zero SQL migrations or schema modifications are needed.

</details>

<details>

<summary><strong>What is the resmon / CPU performance of this resource?</strong></summary>

**0.00ms.** During idle gameplay, the script maintains strict zero-tick performance. During the rare moments the in-game warning window is open, it runs under 0.01ms.

</details>

<details>

<summary><strong>Can I test the warning screen without reconnecting?</strong></summary>

**Yes!** Simply use the admin test command:

```
/testnamecheck
```

This renders the entire interactive glassmorphism warning card on your screen immediately.

</details>

<details>

<summary><strong>Can I translate all messages to my native language?</strong></summary>

**Yes!** All UI texts, buttons, guidance instructions, and connection card headers can be fully translated in `Config.Locales` inside `config.lua`.

</details>

***

### 💬 Still Need Help?

If you've followed these steps and are still facing difficulties, join our [**Discord Server**](https://discord.gg/2yuPTmsqjX) and open a support ticket.

***

-# © 2026 Zynox Development • [Official Store](https://zynoxdev.tebex.store/) • [Discord](https://discord.gg/2yuPTmsqjX)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://zynoxdev.gitbook.io/docs/zynox-resources/zx_nameguard/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.