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

# Troubleshooting

> Resolve common CLI, OAuth, MCP, preview, and display setup problems.

## `niblet` is not found

Confirm the install directory is on `PATH` and open a new shell. Run `command -v niblet` and `niblet version`.

## OAuth opens but never finishes

Keep the CLI running until the browser returns to `127.0.0.1`. Do not close the terminal or reuse an old authorization URL. If another machine opened the URL, the callback still needs to reach the CLI machine.

## MCP is configured but tools are missing

Restart the MCP client after changing its configuration. Check the client's MCP status panel or command, then authenticate the Niblet server. Confirm the URL is exactly `https://cloud.heyniblet.com/mcp`.

## Local preview fails

Run `niblet apps validate .` for a concise project error. Confirm the directory contains `manifest.yaml` and exactly one top-level `.star` file. Check that `main()` returns a `render.Root` widget.

## App works locally but not in hosted review

Look for local filesystem assumptions, private network endpoints, unapproved redirects, missing configuration defaults, or protected values that were placed in ordinary config.

## Display setup cannot find the device

Use a data-capable USB cable, connect directly instead of through a hub, and confirm the browser supports Web Serial. If a firmware write was interrupted, reconnect in bootloader mode and reinstall the matching image.