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

# Troubleshooting Guide

## Potential Issues

### Cannot Start Throw

**Symptom**: Pressing the throw key does nothing.

**Possible Causes**:

* `GetCurrentItem()` returns `nil`
* Returned item is missing `id`
* Returned item is missing both `model` and `hash`
* `CanThrowItem(item)` returns `false`
* Throw attempt occurs during anti-spam window

**Solutions**:

1. Log the object returned by `GetCurrentItem()`.
2. Confirm `id`, `itemCode`, and `name` are populated.
3. Ensure either `model` or `hash` is provided.
4. Temporarily return `true` in `CanThrowItem` to isolate logic issues.
5. Avoid rapid re-presses while testing.

### Items Not Removed On Throw

**Symptom**: Thrown item remains in inventory.

**Possible Causes**:

* `OnItemThrown(...)` integration is incomplete
* Wrong item key used in inventory remove function
* Slot/metadata mismatch in framework remove call

**Solutions**:

1. Add debug prints in `OnItemThrown(...)`.
2. Verify `item.itemCode`, `item.slot`, and `item.amount` mapping.
3. Confirm your inventory export returns success.

### Items Not Added On Pickup

**Symptom**: Pickup animation/prompt works, but item is not added.

**Possible Causes**:

* `OnItemPickedUp(...)` add logic failed
* Metadata format not accepted by inventory system
* Inventory full or blocked by framework conditions

**Solutions**:

1. Add debug logs in `OnItemPickedUp(...)`.
2. Validate metadata format passed to add-item function.
3. Test with `amount = 1` and minimal metadata.

### Pickup Prompt Never Appears

**Symptom**: Item is on ground, but no interaction prompt is shown.

**Possible Causes**:

* `Config.PickUpDistance` too low
* `NearGroundItem(...)` draw code not running
* Prompt hidden by custom dead/downed checks

**Solutions**:

1. Increase `Config.PickUpDistance` during testing.
2. Add temporary prints in `NearGroundItem(...)`.
3. Confirm your dead-state checks are correct.

### Throw Arc Feels Laggy

**Symptom**: Frame drops while charging throw.

**Possible Causes**:

* Arc simulation settings too high
* Server has many simultaneous throw previews

**Solutions**:

1. Lower `Config.Physics.ArcThickness`.
2. Lower `Config.Physics.ArcMaxSteps`.
3. Increase `Config.Physics.ArcSimulationStep` slightly.

### Throwables Persist After Script Stops

**Symptom**: World clutter remains after restarts or reloads.

**Possible Causes**:

* Resource stop handling interrupted
* Manual cleanup never triggered in custom workflows

**Solutions**:

1. Ensure resource stop handler remains intact in `sv_funcs.lua`.
2. Call `ClearAllThrownItems()` before maintenance restarts.
3. Use `ClearPlayersThrownItems(source)` on custom disconnect workflows.

## Debug Checklist

1. Validate item payload from `GetCurrentItem()`.
2. Confirm client throw starts and reaches server event.
3. Confirm `OnItemThrown(...)` and `OnItemPickedUp(...)` both execute.
4. Verify inventory remove/add API return values.
5. Test with a simple known-good item and minimal metadata first.


---

# 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://nodemods.gitbook.io/nodemods-docs/throwable-items/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`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.