Troubleshooting
An error message or something that won't work? Find your problem and follow the fix.
Find what you're seeing below. Click the problem for the fix.
| What you see | Fix |
|---|---|
| Publishing fails with a build error | Build error |
| Publishing fails while starting | Website won't start |
| "This website is being set up" at your address | Website being set up |
| The browser doesn't open to log in | Logging in through the browser |
git or node not found |
Git or Node.js not found |
npx not found |
npx not found |
EBADENGINE or "Unsupported engine" |
Node.js too old |
claude not found |
Claude Code not found |
| Red message: "running scripts is disabled" (Windows) | Scripts disabled |
| "Permission denied" or "Access denied" | No permission |
| "Changes were (just) made elsewhere" | Changes made elsewhere |
| Your change isn't online | Old version showing |
| Your account is still waiting for approval | Account not approved |
| Your own domain name doesn't work | Connecting a domain name |
#Build error
Your AI reports that building failed. There's a mistake in the code your AI wrote. Your previous version is still online.
- Tell your AI: "Publishing failed. Read the error message, fix it and try again."
- Still failing after a few attempts? Have your AI run the build on your computer first
(
npm run buildoften shows the same error), or roll back the last change. - In the dashboard, Publishes shows the explanation and the full build log.
#Website won't start
Building worked, but your website didn't answer within 60 seconds. Often a setting is missing, or the website gets stuck while starting.
- Did you just add or change a setting? Check its name and value in settings and secrets.
- Ask your AI: "The website won't start after publishing. Check the build log and the logs and fix it."
#Website being set up
At your web address you see a Switchboard page: "This website is being set up" or "This website is paused". That means no working version is live (yet).
- Just created? The first publish takes about two minutes. Refresh the page in a bit.
- Does it say "There's a problem" or "Not working right now"? The first version didn't work. See build error.
- Does it say "Switched off" or "Stopped"? Click Start in the dashboard.
- Paused? Your account is paused. Contact us.
- Only on your own domain name? Then your domain name isn't fully connected yet. See connecting a domain name.
#Logging in through the browser
With init or login your browser should open a page to approve the connection.
- Nothing opens? Your terminal shows an address (something with
/app/cli?code=) and a code likeKDTM-WQPL. Copy the address into your browser and click Give access. - "Code expired"? A code is valid for 10 minutes. Run the command again.
- You see a login screen? Log in to Switchboard first; you'll then get to the approval page automatically.
- Working on a computer without a browser (a server, for example)? Open the address on your phone or another computer. That works too.
#Git or Node.js not found
You see something like git: command not found or 'node' is not recognized.
- Close your terminal and open a new one. After installing, an open terminal doesn't know about the new program yet.
- Check with
git --versionandnode --version. - Still nothing? Install them again following install Node.js and Git.
- On Windows, restarting your computer can also help.
#npx not found
npx comes with Node.js. Seeing npx: command not found or 'npx' is not recognized?
- Close your terminal and open a new one.
- Check that Node.js is there:
node --version. No version number? Install Node.js. - Is the version lower than 24? See Node.js too old.
#Node.js too old
While setting up your website (npm run setup or npm install) you see EBADENGINE,
Unsupported engine or required: { node: '>=24' }. Your website needs Node.js 24 or newer,
and your computer has an older version. Publishing still works, but the preview on your own
computer doesn't.
- Check your version with
node --version. - Lower than
v24? Install Node.js again following install Node.js and Git. For Linux it shows how to get version 24; your system's own version is often too old. - Close your terminal, open a new one and tell your AI: "Node.js has been updated. Run
npm run setupagain."
#Claude Code not found
Seeing claude: command not found or 'claude' is not recognized?
- Close your terminal and open a new one.
- Install Claude Code again following the guide.
- Still not working? On a Mac or Linux it often helps to paste this command and then open a new terminal:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc#Scripts disabled (Windows)
PowerShell shows a red message like:
npx : File C:\Program Files\nodejs\npx.ps1 cannot be loaded because running scripts is disabled on this system.Windows is then blocking programs like npx. Allow them for your user with this command:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedType Y and press Enter when asked. Then try again.
#No permission
You see Permission denied, EACCES or Access denied.
With
npm install -gon Linux or a Mac? npm isn't allowed to write to the system folder. Don't usesudo; let npm put programs in your own folder from now on instead. Paste these two lines once, close your terminal, open a new one and try again:npm config set prefix ~/.local echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcThe Switchboard commands themselves need no install:
npx -y @switchboard-host/cli@latestalways works.When publishing ("authentication failed" or "403")? Your connection was revoked or has expired. Log in again with
npx -y @switchboard-host/cli@latest login."Account not approved"? See account not approved.
On Windows, in a folder like
C:\Program Files? Work in your own folder instead, like Documents.
#Changes made elsewhere
You see a message like "Changes were just made elsewhere." or "Changes were made elsewhere (for example on another computer or on GitHub), so your changes were not saved yet." Switchboard has a newer version than your computer, for example because you changed something on another computer or on GitHub. Nothing is lost: your changes are still on your computer. Tell your AI: "Fetch the latest version, merge the changes and publish again." See using GitHub.
#Old version showing
You published something, but you don't see it.
- Refresh the page without cache: Ctrl+F5 (Mac: ⌘ Cmd+Shift+R).
- In the dashboard, check under Publishes whether the latest version is Live.
- Failed? See build error.
#Account not approved
While your account is waiting for approval, you can log in and read the guide, but not yet create or publish websites. We approve your account after the welcome call. Taking long? Contact us.
#Still stuck?
Run this command in your website's folder. It checks everything and tells you what's wrong:
npx -y @switchboard-host/cli@latest doctorCan't work it out? Contact us and include the message you see.