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

# Troubleshooting

> Fix common atlasFishing install and gameplay issues — start order, name guard, items, NUI, icons, and more.

Most `atlasFishing` issues trace back to start order, a renamed folder, missing items, or a missing NUI build. Work top to bottom.

## Startup & dependencies

<AccordionGroup>
  <Accordion title="Resource blocked: name mismatch in console">
    `shared/guard.lua` requires the folder to be named exactly `atlasFishing`. If the console prints a name-mismatch warning, the resource has disabled itself.

    Rename the folder back to:

    ```text theme={null}
    atlasFishing
    ```

    Then restart it. Do **not** use `atlas-fishing`, `fishing`, or anything else — the guard intentionally blocks renamed installs because the bridge, NUI callbacks, and setup all assume the exact name.
  </Accordion>

  <Accordion title="Bridge not found / resource won't initialize">
    `atlasFishing` declares `dependency 'atlasBridge'` and needs it started **first**:

    ```cfg theme={null}
    ensure atlasBridge
    ensure atlasFishing
    ```

    Also confirm the bridge folder is named exactly `atlasBridge`. If `atlasBridge` starts after `atlasFishing`, fishing will not initialize.
  </Accordion>
</AccordionGroup>

## Ped & interaction

<AccordionGroup>
  <Accordion title="Fisherman ped does not spawn">
    * Confirm `Config.enabled = true` and the resource is not blocked by the name guard.
    * `Config.ped.coords` is a placeholder by default — you may be at the wrong spot. Use the map blip (`Config.ped.blip`) to find it.
    * Make sure `atlasBridge` started first; the ped is created through the bridge.
    * If `Config.ped.interact.method = 'target'`, confirm `ox_target` or `qb-target` is installed and detected by the bridge — otherwise switch back to `interact` or `textui`.
  </Accordion>
</AccordionGroup>

## Shop, items & icons

<AccordionGroup>
  <Accordion title="Shop or minigame does not open (blank NUI)">
    Confirm the NUI build is present:

    ```text theme={null}
    atlasFishing/web/dist/index.html
    ```

    The supplies shop, boat shop, and minigames all render from this page. If `web/dist` is missing, reinstall the resource package, or rebuild from source:

    ```bash theme={null}
    cd web
    bun install
    bun run build
    ```
  </Accordion>

  <Accordion title="Cannot buy items">
    * The item key exists in your inventory (see [Items & Icons](/atlas-fishing/items)).
    * The payment account in `Config.shop.payments` is valid for your framework.
    * The player has enough money.
    * The bridge detected the correct framework and inventory — check the console for a provider error.
  </Accordion>

  <Accordion title="Item icons are blank">
    * You copied the right format — try the PNG set first (`items/icons/png`).
    * The icons are in your inventory's image folder (e.g. `ox_inventory/web/images/`).
    * The filenames match the item keys if your inventory expects that.
  </Accordion>
</AccordionGroup>

## Gameplay

<AccordionGroup>
  <Accordion title="Rod cannot be used">
    * The player has `fishing_rod` and at least one bait.
    * `Config.enabled = true` and the resource is not name-guard blocked.
    * The player is near/facing water if `Config.cast.requireWater = true`.
  </Accordion>

  <Accordion title="No fish received after a successful minigame">
    * The catch item keys exist in your inventory.
    * The inventory has room/weight available.
    * The minigame did not finish faster than `Config.minigame.minMs` (a too-fast success is rejected server-side).
    * The bait did not roll a `fail` (catch nothing) — that is expected occasionally.
    * The server console shows no item-grant errors.
  </Accordion>

  <Accordion title="Fishing does not cancel on death">
    Fishing should cancel if the player dies during a cast, bite wait, or minigame.

    * `Config.death.enabled = true`.
    * `atlasBridge` starts before `atlasFishing`.
    * Your death system fires a normal death event, or you set the bridge convar:

    ```cfg theme={null}
    setr atlas:deathEvent "baseevents:onPlayerDied"
    ```
  </Accordion>

  <Accordion title="Selling does not pay">
    * The player has sellable fish (junk is not sellable).
    * `Config.sell.account` is valid for your framework.
    * The fish entries have `price` values.
    * The inventory provider can remove the fish item.
  </Accordion>

  <Accordion title="Boat rental issues">
    * `Config.boatrental.enabled = true`.
    * `Config.boatrental.spawn` points at valid water (the default is a placeholder).
    * The boat model exists.
    * The player has enough money in `Config.boatrental.account`.
    * The server console shows no vehicle-spawn or permission errors.
  </Accordion>
</AccordionGroup>

## General debugging

<Steps>
  <Step title="Turn on debug temporarily">
    Set `Config.debug = true`, restart, reproduce the issue, then turn it off.
  </Step>

  <Step title="Read the server console">
    Look for resource-name, bridge, inventory, or NUI errors.
  </Step>

  <Step title="Test one system at a time">
    Shop → rod use → minigame → item grant → selling → boat rental.
  </Step>

  <Step title="Revert recent config changes">
    If the default config worked, compare your changed item keys, accounts, and coordinates.
  </Step>
</Steps>