Troubleshooting
Fixes for the problems people hit most, collected in one place.
Find your symptom below. Short fixes are given here; the links go to the full explanation on the page that covers the topic.
Install and the CLI
nitrostack-cli: command not found. The CLI isn't on your path. Install it with npm install -g @nitrostack/cli, or run it without installing: npx @nitrostack/cli --version.
Permission errors when installing globally. Point npm at a directory in your home folder, or use a Node version manager such as nvm:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATHMore: dependency install problems, generate problems.
Running the server
The port is already in use. Another process holds it, often a second copy of the server. Find it with lsof -i :3001 (or the port in the error) and stop it. More: Dev Command, which also covers TypeScript errors, widgets not loading, and hot reload not working.
Studio shows the project as disconnected. Run npm run build in a terminal and fix any TypeScript errors it reports. A server that fails at startup prints the reason in Studio's Logs, under Server Logs. More: Verify and debug transports.
Connecting clients
HTTP clients get connection refused. The server is running over STDIO only. Check that NODE_ENV=production or MCP_TRANSPORT_TYPE is set, then confirm with curl http://localhost:3000/mcp/health.
It works on your machine but not from another one. The server is listening on localhost. Set HOST=0.0.0.0.
More: Dual transport.
Widgets
A widget shows "Loading..." forever, or its data is null. See Migrate to useWidgetSDK.
A widget doesn't appear in Studio, or shows the wrong data. See Widget manifest.
The widget isn't in widget://examples. Check that src/widgets/widget-manifest.json exists and is valid JSON. The manifest is read when the server starts, so restart it after editing. More: Widget examples.
Docker and deployment
The port is published but connections are refused. The server is listening on localhost inside the container. Set HOST=0.0.0.0.
Widgets don't render. The image is missing src/widgets/out. Confirm that npm run build ran in the build stage and that the Dockerfile copies the folder.
The container exits right away. Read its output with docker logs mcp-server.
More: Deploy with Docker, Python on Docker.
File uploads
A file doesn't decode, a large file runs out of memory, or the extension doesn't match. See File uploads.
Still stuck?
If the answer isn't here, see Support for where to ask, and what to include.