> For the complete documentation index, see [llms.txt](https://docs.nxcframework.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nxcframework.net/running-your-server/troubleshooting.md). # When something goes wrong Working out why something is not behaving. ## Start here ``` nxc_versions ``` If the versions do not all come from one [compatibility set](/reference/compatibility-sets.md), stop and fix that. It is the cause of most confusing behaviour, and everything below assumes a consistent set. ## By symptom | Symptom | Most likely cause | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `attempt to index a nil value (global 'Nxc')` | `nxc_lib` missing, or older than the set | | `attempt to index a nil value (global 'os')` | A resource using server-only code on the client. Report it | | A resource starts and does nothing at all | It has no entry point, or a dependency did not start | | Two resources disagree in the log, one tick apart | Version mismatch between them | | Cursor stuck, cannot move | An interface kept focus. `/nxcui close` frees it; reconnecting always does | | Settings ignored | The resource never registered. Check `nxc_config_status` | | An interaction option never appears | Hold the key and watch the crosshair. **Dim** means the ray hit nothing. **White** means it hit something and nothing applies — usually distance, or a capability you do not hold. **No crosshair at all** means the keybind is not bound: Settings, Key Bindings, FiveM | | An option you expect is missing | Capabilities are never granted yet, so **every capability-gated option is currently refused** | | An interaction appears and does nothing | The server refused it. The reason is in the server log | ## Reading a refusal When the server refuses an interaction it says why: ``` [WARN] nxc_target target.selection_refused connection=5 option=my_doors:open reason=too_far ``` | Reason | Meaning | | ------------------ | -------------------------------------------------------------------- | | `too_far` | The server measured a greater distance than the client did | | `distance_unknown` | The server could not resolve the entity. Refused rather than assumed | | `missing_item` | Item-gated, and there is no inventory yet, so it is always refused | | Missing capability | Capability grants are not populated yet, so this is always refused | Three of those are the framework failing closed on features that do not exist yet. They are not misconfiguration. ## Correlation IDs Operations carry an identifier through every resource they touch. When a player reports a failure, the identifier from the error turns "something broke" into a single searchable trace. ## When to report it If the server log shows a Lua error inside an `nxc_` resource, that is a defect rather than a configuration problem. Include the whole stack trace, the output of `nxc_versions`, and what you were doing. See [Getting help](/reference/help.md). --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nxcframework.net/running-your-server/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.