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

# Troubleshooting

> Fixes for the common first-run and hardware issues.

<AccordionGroup>
  <Accordion title="Shell integration warning on first run">
    Restart VS Code and open a new terminal session.
  </Accordion>

  <Accordion title="Linux notifications (ENOENT on task completion)">
    Install the notification helper: `sudo apt install libnotify-bin`
  </Accordion>

  <Accordion title="J-Link not detected / board not auto-detected">
    Confirm the [SEGGER J-Link drivers](https://www.segger.com/downloads/jlink/) are installed and the board enumerates in `nrfjprog --ids`. Re-plug the board and reload the VS Code window.
  </Accordion>

  <Accordion title="Flash command fails">
    Make sure no other tool (nRF Connect for Desktop, OpenOCD) holds the J-Link interface. Only one process can flash at a time.
  </Accordion>

  <Accordion title="ESP-IDF not detected">
    Confirm ESP-IDF is installed and `IDF_PATH` is set in the environment VS Code launched from. The [Espressif IDF extension](https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension) sets this up for you; after installing it, reload the VS Code window.
  </Accordion>

  <Accordion title="ESP serial port not found">
    Check that the board enumerates as a serial port. Most ESP dev boards need a USB-to-UART driver: CP210x or CH340 depending on the board. Install the driver, re-plug the board, and reload the window.
  </Accordion>

  <Accordion title="ESP flash fails">
    Confirm the correct serial port and chip target are selected, no serial monitor is holding the port, and the board is in download mode (some boards need the BOOT button held while connecting). Then retry the flash.
  </Accordion>

  <Accordion title="AI provider authentication errors">
    Verify your API key in the extension settings and that the endpoint URL matches your provider (for example `https://openrouter.ai/api/v1` for OpenRouter).
  </Accordion>

  <Accordion title="Model refuses tool calls or returns plain text">
    The configured model must support native tool-calling. Models without function-calling cannot drive hardware workflows. See [Models](/models).
  </Accordion>
</AccordionGroup>

Still stuck? [Open a Discussion](https://github.com/adsumnetworks/Adsum-IoT-Coder/discussions). We read every one.