---
title: Setup
description: Fix the problems your machine's tools run into before a build or a local run, such as npm blocked or a web request failing in Windows PowerShell.
slug: /troubleshooting/setup
order: 1
visibility: public
redirects_from: []
---

# Setup

These entries cover the tools on your machine that a build, an upload, or a local run uses. [What your computer needs](/cloud/getting-started/prerequisites/) lists those tools and the versions the platform runs.

## PowerShell says running scripts is disabled when npm runs

**Cause.** In PowerShell, `npm`, `npx`, and the installed `turnzero` run as scripts, and Windows PowerShell's default execution policy, `Restricted`, blocks every script before it starts.

**Check.** The error mentions `npm.ps1`, `npx.ps1`, or `turnzero.ps1` and says that running scripts is disabled on this system. `Get-ExecutionPolicy` returns `Restricted`, and the same command runs when you call it as `npm.cmd`, `npx.cmd`, or `turnzero.cmd`.

**Remedy.** Run `npm.cmd` with the same arguments, `npx.cmd` in place of `npx`, and `turnzero.cmd` in place of `turnzero`, as in `npm.cmd install`. A line a tool call returns already has a Windows form with `turnzero.cmd`. [Windows PowerShell](/cloud/getting-started/prerequisites/#windows-powershell) gives the rest: a line you write by hand, a `.ps1` script of your own run for one process, and the other changes the commands on these pages need there.

## The deploy line prints an npm notice, and PowerShell shows it as an error

**Cause.** A notice of a newer version can come from two places. The [turnzero command](/cloud/concepts/turnzero-command/) checks at most once a day under `turnzero deploy`, `turnzero check`, and `turnzero login`. It prints one line naming `npm install -g turnzero@<tag>` where a newer version is out. A line run through `npx` without `--no-update-notifier` can also get npm's own notice on standard error. Every `npx` line a tool call returns includes that flag. Windows PowerShell shows a native command's standard error as an error record when the output is redirected with `2>&1`. Neither is a failure of the command.

**Check.** The line begins `npm notice`. The command's own notice is instead one line naming `npm install -g turnzero@<tag>` or `npx --no-update-notifier -y turnzero@<tag>`. The command also prints it when the platform's health response reports a newer version, even under `CI`. Where the line ran through npx, the notice names the npx form, with `npx.cmd` on Windows. The command's exit status is 0, and it still printed its own lines, such as the deploy line's steps to the deploy's outcome or the `hash` line's `sha256:` line.

**Remedy.** None is needed. Read the command's own lines and its exit status. To take the newer version, run the line the notice names, once. You or your tool can run it. The `npm install` form installs the newer command, and the npx form runs it. The notice from npm comes only with a line run through `npx` without the flag, such as one written by hand. Write `--no-update-notifier` before `-y`, as the returned lines do. Or set `npm_config_update_notifier=false` in the shell that runs the lines, which npm reads for every `npx` run.

## A line of the command says it needs Node.js 24 or later

**Cause.** The [turnzero command](/cloud/concepts/turnzero-command/) runs on Node.js 24 or later. Under an older release, it checks the version first and stops, so it reads nothing and starts nothing.

**Check.** The command printed one line. Its first sentence contains the words "Node.js 24 or later" and gives the version the command found. The command's exit status is 3. `node --version` prints a version below `v24`.

**Remedy.** Install Node.js 24 or later, as [What your computer needs](/cloud/getting-started/prerequisites/#check-your-node-js-version) describes. Then run the line again. Where the line pipes a token code to `token claim`, the code was not read, and the same line works once Node.js is updated. Where the code has expired by then, the line's refusal says to call `mint_token` again and run the line it returns. For your own `turnzero login`, run `login` again.

The line `turnzero authorize --mint <id>` carries no code, so nothing was presented. Run the same line again once Node.js is updated.

## A nested npx command fails with npm EUSAGE

**Cause.** The returned command is wrapped in a second npx command to select Node.js. The wrapper can change npm's argument parsing and which `node` executable is found on `PATH`.

**Check.** Look for an outer `npx --package=node@24 -c ...` around the returned command. Check `node --version` in the shell that will run that command.

**Remedy.** Use Node.js 24 or later directly in that shell, with its executable folder first on `PATH`. Check `node --version` again, then run the returned line unchanged, without another npx wrapper. [Check your Node.js version](/cloud/getting-started/prerequisites/#check-your-node-js-version) explains how to select the version. Ask before updating Node.js on the person's computer.

## npm install -g node ends with EEXIST

**Cause.** `npm install -g node`, or `npm install -g node@24`, writes a `node` file into npm's global folder. Where Homebrew or another tool installed the Node.js you have, that tool owns the file, so npm refuses to replace it.

**Check.** npm ended with status 1 and code `EEXIST`, naming the `node` file, such as `/opt/homebrew/bin/node`. `node --version` still prints the older version.

**Remedy.** Get Node.js 24 the way your current one came, as [What your computer needs](/cloud/getting-started/prerequisites/#check-your-node-js-version) describes: Homebrew's `node@24`, a version manager, or the installer from nodejs.org. Don't add `--force`, which would overwrite the other tool's file. Then run `npm install -g turnzero`.

## No PostgreSQL to run against before the first deploy

**Cause.** You want to run a database app on your machine before its first deploy, but no PostgreSQL server is available.

**Check.** Find out whether PostgreSQL is installed, Docker is running, or Node.js and npm are available for PGlite.

**Remedy.** Follow [Run against your own PostgreSQL](/cloud/guides/run-your-application-on-your-machine/#run-against-your-own-postgresql) to start a server and set the application's database connection. This route needs no sign-in if the app reads none of the three platform settings listed there. Use the provisioned run when it needs platform services or shared development data.

## Your tool refuses a background process or a file deletion

**Cause.** Your coding tool refused the command under its own command policy on your machine, such as a sandbox that blocks `Start-Process` or `Remove-Item`. Turn Zero Cloud sets no policy on your machine and cannot list another product's.

**Check.** The refusal mentions the tool's policy or its sandbox, and no refusal name of the platform.

**Remedy.** Before the first deploy, run the application on your machine and request its health path. That check needs no server left running in the background. The script below starts `src/main.mjs` as a child process with `PORT` set. It requests `/health` until it returns 200 or 30 tries pass, prints each status, and stops the child. Change the entry and the path to your own.

Save the script as `check_local.mjs` in the application's folder, and run `node --env-file=.env check_local.mjs` as one command. It exits 0 only when its own child returned 200. Where the child stops early, for example because another process holds the port, the check fails. The script stops the child on every way out, and gives each attempt two seconds. [Check the run in one command](/cloud/guides/run-your-application-on-your-machine/#check-the-run-in-one-command) gives the same check in a POSIX shell, as three lines run as one command.

```js
// check_local.mjs: start the service, check its health path, then stop it.
import { spawn } from 'node:child_process';

const port = '8090';
const child = spawn(process.execPath, ['src/main.mjs'], { env: { ...process.env, PORT: port }, stdio: 'inherit' });
let exited = false;
child.on('exit', () => { exited = true; });
const stop = () => { if (!exited) child.kill(); };
process.on('exit', stop);
for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => { stop(); process.exit(1); });
let healthy = false;
for (let attempt = 1; attempt <= 30 && !healthy && !exited; attempt += 1) {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  if (exited) break;
  try {
    const response = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2000) });
    console.log(`attempt ${attempt}: ${response.status}`);
    healthy = response.status === 200;
  } catch {
    console.log(`attempt ${attempt}: no answer yet`);
  }
}
if (exited) console.log('the service stopped before the check ended');
stop();
process.exitCode = healthy && !exited ? 0 : 1;
```

Three steps on these pages use `Remove-Item`, so a tool that refuses it refuses them too. Two clear a shell variable before a local run: the reset in [Add a database](/cloud/guides/add-a-database/#5-develop-locally), and the remedy in [Secrets](/cloud/troubleshooting/secrets/#a-local-run-is-refused-or-reaches-the-wrong-application-though-env-is-current). In a Unix-style shell, use the `env -u` form both pages give. In PowerShell, set each name to nothing in the same invocation instead: `$env:APP_DATABASE_URL = $null; node --env-file=.env …`. For the second page, also set `$env:TURNZERO_CLOUD_APP_TOKEN = $null`.

The third is the PowerShell form of the unattended step in [Keep a secret value out of chat](/cloud/guides/supply-a-secret-value-without-exposing-it/#when-no-person-is-present). It writes a temporary value file, stores it, and then removes it with `Remove-Item`, in one line. Where your tool refuses the line before it runs, nothing ran and no file was written. Your tool then hands you the step to run. Where it refuses only the `Remove-Item` at the end, the value file stays in the temporary folder, holding the secret. Your tool never reads that file. It tells you the path, and you delete the file yourself.

No step on these pages deletes `.env`. The provision line replaces its own settings in an existing file and keeps every other line. Do not bypass your tool's refusal to run a command. If your tool refused to delete a file, the file stays until you delete it.

## Invoke-WebRequest fails because the Internet Explorer engine is not available

**Cause.** In Windows PowerShell 5.1, `Invoke-WebRequest` parses each response with the Internet Explorer engine unless the command passes `-UseBasicParsing`. Where that engine is missing or was never set up, the command fails after the request.

**Check.** The error says that the response content cannot be parsed because the Internet Explorer engine is not available. The command has no `-UseBasicParsing` switch.

**Remedy.** Add `-UseBasicParsing` to the command. The `commands.powershell` line that `mint_upload_grant` returns already has it, and a deploy through the turnzero command runs no `Invoke-WebRequest`. To see an error response's status and body, run `curl.exe -i` instead, as [Windows PowerShell](/cloud/getting-started/prerequisites/#windows-powershell) describes.

## A JSON body sent with curl.exe arrives without its quotes

**Cause.** Windows PowerShell 5.1 passes an argument to a program such as `curl.exe` without escaping the double quotes inside it. So `--data '{"title":"first"}'` reaches curl as `{title:first}`, which is not JSON. An inline `node -e` script loses its double quotes the same way, and [Windows PowerShell](/cloud/getting-started/prerequisites/#windows-powershell) gives its two working forms.

**Check.** The command ran in Windows PowerShell 5.1 with the body written inline. Your application refuses the body as malformed, and the same command succeeds in bash. The service in [Build a database-backed service](/cloud/getting-started/build-a-database-backed-service/) returns 400 `invalid_json`; one an earlier template wrote returns 400 `invalid_note`.

**Remedy.** Write the body to a file without a byte-order mark, in the temporary folder so the next deploy does not ship it, and send the file with `curl.exe`.

```powershell
[System.IO.File]::WriteAllText("$env:TEMP\body.json", '{"title":"first"}')
curl.exe -i -H 'Content-Type: application/json' --data-binary "@$env:TEMP\body.json" 'https://<label>.ai.host/<path>'
```

Or send the body with `Invoke-RestMethod`, a PowerShell command that passes it unchanged.

```powershell
Invoke-RestMethod -Method Post -ContentType 'application/json' -Body (@{title='first'} | ConvertTo-Json -Compress) -Uri 'https://<label>.ai.host/<path>'
```

In bash, the body passes unchanged with the inline form.

```bash
curl -H 'Content-Type: application/json' --data '{"title":"first"}' 'https://<label>.ai.host/<path>'
```

## A deploy refuses a zip built on Windows because an entry contains a backslash

**Cause.** Windows PowerShell 5.1's `Compress-Archive` writes `\` between the segments of each entry's name, as in `migrations\0001_guestbook_messages.sql`. A zip allows only `/` there, so the deploy refuses the zip and does not count it as a deploy.

**Check.** The `deploy` response is 400 `artifact_layout_invalid`. Its detail gives the entry, says it contains a backslash, and points to the `tar.exe` command of step 3 (Build and upload the artifact) of Deploy from your computer.

**Remedy.** Leave the zip to the [turnzero command](/cloud/concepts/turnzero-command/): call `deploy_command` from your tool and run the line its response returns. Or build the zip with the `tar.exe` command [Build and upload the artifact](/cloud/getting-started/deploy-an-application/#3-build-and-upload-the-artifact) gives.
