Setup #

View this page as Markdown

On this page

These entries cover the tools on your machine that a build, an upload, or a local run uses. What your computer needs 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 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 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 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 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 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 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 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 gives the same check in a POSIX shell, as three lines run as one command.

// 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, and the remedy in Secrets. 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. 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 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 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 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.

[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.

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.

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: 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 gives.