> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/police-and-medical/cuxial-diseases/troubleshooting.md).

# Troubleshooting

Common Cuxial Diseases problems, with their cause and fix.

The most frequent problems after installing Cuxial Diseases, with the cause and the fix for each one.

<details>

<summary>The resource does not start</summary>

**Cause.** A dependency is missing or starts later. Cuxial Diseases needs OneSync, `ox_lib`, `oxmysql` and `cuxial_bridge`.

**Fix.** Enable OneSync and start the dependencies first:

{% code title="server.cfg" %}

```cfg
ensure ox_lib
ensure oxmysql
ensure cuxial_bridge
ensure cuxial_diseases
```

{% endcode %}

</details>

<details>

<summary>Every player got sick a few days after the install</summary>

**Cause.** The vaccination deadline is enabled (`onboarding.enabled = true`). Existing characters get `onboarding.hoursExisting` hours from their first login and new ones get `onboarding.hours`. Whoever is not vaccinated in time catches the disease in `onboarding.disease`.

**Fix.** Make sure the vaccine item exists and players can get it, or set `onboarding.enabled = false`. To spare only the characters that already existed, set `onboarding.applyToExisting = false`. Staff can cure a player with `/disease cure` and restart their deadline with `/disease onboarding <id>`.

</details>

<details>

<summary>The console shows an "onboarding" error when a player logs in</summary>

**Cause.** The vaccination deadline reads the character table of the framework and needs the columns `id` and `citizenid`. They exist on QBox and QBCore, not on ESX.

**Fix.** On ESX, keep `onboarding.enabled = false`. If you use a custom character table, check the table name set for `cuxial_bridge`.

</details>

<details>

<summary>Using an item does nothing, or the inventory reports a missing export</summary>

**Cause.** One of these:

* The item is not named in `data/diseases.lua` as `test.item`, `treatment.item`, `treatment.box.item` or `vaccine.item`, so the script registers no export for it.
* `server.export` in the item definition does not match `cuxial_diseases.<item name>`.
* The resource folder was renamed.
* The test is marked `external = true` in the catalog, so another resource has to handle it.

**Fix.** Use the exact item name of the catalog in both places and keep the folder name `cuxial_diseases`. Restart the server after changing the catalog.

</details>

<details>

<summary>A medicine answers "You don't need this"</summary>

**Cause.** The player has no active disease treated by that item. The item is not consumed.

**Fix.** None needed. Check what the player has with `/disease status <id>`.

</details>

<details>

<summary>A pill is rejected because the previous one is still active</summary>

**Cause.** The next dose is only accepted once the previous one has run out, or after `treatment.minIntervalHours` when the disease sets it.

**Fix.** Wait the hours shown in the message, or lower `minIntervalHours` for that disease.

</details>

<details>

<summary>The doses taken went back to zero</summary>

**Cause.** The player went too long without a dose. After `treatment.resetAfterHours` since the last one, twice `effectHours` by default, the routine counts as broken and the count starts again.

**Fix.** Raise `resetAfterHours` for that disease, or set it to `0` so the count is never lost.

</details>

<details>

<summary>A sick player has no symptoms</summary>

**Cause.** One of these:

* `symptoms.enabled` is `false`.
* The current stage has no symptoms, as in an incubation stage.
* A dose is active and the treatment has `suppressSymptoms = true`, or it reduces them.
* The player is dead or unconscious and `symptoms.skipWhenDead` is `true`.
* The player is inside a vehicle: cough, dizziness, vomiting and fatigue wait until they get out.
* Not enough time has passed. Intervals are minutes of play and each one is random between `min` and `max`.

**Fix.** Check the case with `/disease status <id>`, move it with `/disease stage` and test the animations with `/disease symptom <id>`.

</details>

<details>

<summary>Nobody catches anything from sick players</summary>

**Cause.** Proximity contagion is disabled by default. With it enabled, a disease only spreads when it has `contagion.proximity`, the sick player is in one of the stages listed there and the other player is inside the radius. A mask in the inventory, an immunity or a vaccine lower or remove the risk.

**Fix.** Set `proximity.enabled = true` in `shared/config.lua` and restart the resource. Raise `chance` in the catalog for a faster spread.

</details>

<details>

<summary>The patient does not know which disease they have</summary>

**Cause.** `diagnosis.revealToPatient` is `false`. The name stays hidden until the case is diagnosed.

**Fix.** Diagnose the case with a positive test, from the MDT of Cuxial Police or with `/disease diagnose`. To show the name from the start, set `diagnosis.revealToPatient = true`.

</details>

<details>

<summary>A test comes back negative or inconclusive on a sick player</summary>

**Cause.** A test only checks the diseases that name that item in `test.item`. During `incubationHours` the result can be inconclusive, with the percentage in `test.inconclusiveChance`.

**Fix.** Use the test item of that disease, or repeat the test after the incubation time.

</details>

<details>

<summary>/disease answers that you are not allowed, or the command does not exist for you</summary>

**Cause.** The commands need two things: belonging to the ACE group in `admin.restricted` and having the framework permission in `admin.permission`.

**Fix.** Add the staff member to the group in `server.cfg` and give them the admin permission of your framework:

{% code title="server.cfg" %}

```cfg
add_principal identifier.license:xxxxxxxxxxxxxxxx group.admin
```

{% endcode %}

</details>

<details>

<summary>A vaccine is rejected with "the vaccine is useless right now"</summary>

**Cause.** The player already has the disease that the vaccine protects against. A vaccine does not cure.

**Fix.** Treat the disease first and vaccinate afterwards.

</details>

<details>

<summary>A lethal stage never knocks the patient down</summary>

**Cause.** The collapse is carried out by `cuxial_medical`. Without it, the script only sends the `collapse` event. A collapse also needs the patient to be online, with no active dose, and `symptoms.enabled = true` for the one caused by health loss.

**Fix.** Start `cuxial_medical`, or handle the event from your own ambulance script. See [Exports & events](/scripts/police-and-medical/cuxial-diseases/developers.md#hooks).

</details>

<details>

<summary>A doctor cannot complete the cure plan</summary>

**Cause.** The steps of `cure.steps` are applied from the MDT of Cuxial Police. A step with `hours` cannot be done before that time has passed, and a step with `item` needs the doctor to carry it.

**Fix.** Start `cuxial_police`. Without it, complete the steps from your own resource with the `AdvanceCureStep` export, or cure with `/disease cure`.

</details>

<details>

<summary>The Health app is not on the phone</summary>

**Cause.** One of these:

* `lb-phone` is not running.
* `app.enabled` is `false`.
* `app.defaultApp` is `false`, so the app has to be downloaded from the app store of the phone.

**Fix.** Start `lb-phone`, review the `app` block and, to install it on every phone, set `app.defaultApp = true`.

</details>

<details>

<summary>The Health app opens blank</summary>

**Cause.** The interface is not loading. The folder `ui/dist` is missing or incomplete, usually after a partial upload.

**Fix.** Make sure `ui/dist/index.html` and the folder `ui/dist/assets` exist inside the resource. If they do not, copy the resource again from the original package and restart the server.

</details>

<details>

<summary>The appointments tab of the app is always empty</summary>

**Cause.** Appointments come from Cuxial Police. Without that resource there are none.

**Fix.** None needed if you do not use Cuxial Police.

</details>

<details>

<summary>A pregnant character's top changes to the wrong piece of clothing</summary>

**Cause.** `belly.enabled` is `true` and the `drawable` values in `belly.stages` are at their default `0`.

**Fix.** In `data/pregnancy.lua`, put the belly clothing of your server in `belly.stages`, or set `belly.enabled = false`.

</details>

<details>

<summary>No check-up appointments and no EMS alert during a pregnancy</summary>

**Cause.** Both are created through Cuxial Police. Check-ups and the birth appointment also need the pregnancy to be known: a positive test, the MDT or `/pregnancy reveal`.

**Fix.** Start `cuxial_police`. Without it, the pregnancy still advances, labour starts and the birth happens when `labor.durationMin` runs out.

</details>

<details>

<summary>Disease names appear in the wrong language</summary>

**Cause.** Notifications and commands follow the `ox:locale` convar, with `en` and `es` included. The names of diseases, stages, cure steps and pregnancy months are plain text in `data/diseases.lua` and `data/pregnancy.lua`.

**Fix.** Set the convar and translate the texts of both data files:

{% code title="server.cfg" %}

```cfg
setr ox:locale "en"
```

{% endcode %}

</details>

<details>

<summary>A disease disappeared from players after editing the catalog</summary>

**Cause.** Its `id` was renamed or deleted in `data/diseases.lua`. Existing cases keep the old id and stop being processed.

**Fix.** Restore the old `id`. To retire a disease, cure the active cases first.

</details>


---

# 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://docs.cuxial.com/scripts/police-and-medical/cuxial-diseases/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.