Next Steps

Troubleshooting Local Setup

Find the error message you see while setting up a local Laioutr development environment, and how to fix it.

Find the error message you see. The sections follow the order of the setup steps.

Registry and installation

`ERR_PNPM_FETCH_404 … registry.npmjs.org/@laioutr-…` or `is not in the npm registry`

pnpm looked for a Laioutr package on the public npm registry. The project's .npmrc is missing, or it lacks the line for that scope. The App Starter ships this file; projects made from an older starter may not have it. It needs these lines:

.npmrc

shamefully-hoist=true
@laioutr-core:registry=https://npm.laioutr.cloud/
@laioutr-app:registry=https://npm.laioutr.cloud/
@laioutr-org:registry=https://npm.laioutr.cloud/

`ERR_PNPM_FETCH_401` or `E401 Unable to authenticate`

pnpm sent no valid token to the registry.

Run npm whoami --registry https://npm.laioutr.cloud in your home folder. If it fails there too, log in: npm login --registry https://npm.laioutr.cloud.
If it works in your home folder but fails inside the project, the project's .npmrc contains a //npm.laioutr.cloud/:_authToken= line. It overrides your login. Delete that line. Projects made from an older App Starter have it after cp .npmrc.config .npmrc.

`ERR_PNPM_FETCH_403`

The registry refused your token. Run npm whoami --registry https://npm.laioutr.cloud inside the project to find out why:

It fails — your token is invalid or expired. Browser-login tokens expire after 7, 30 or 90 days. Log in again.
It prints your organization — the token is fine, but that organization has no access to the package pnpm tried to download. This happens with @laioutr-org/ apps owned by another organization.

See npm registry for details.

`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`

A change to .npmrc changed how pnpm lays out node_modules, so pnpm must delete it first. It asks for confirmation, which fails in a script or CI. Delete the node_modules folder yourself and run pnpm install again.

`ERR_PNPM_UNSUPPORTED_ENGINE`

Your Node.js version is too old. Install Node.js 22.12 or newer (we recommend 24), then run pnpm install again.

`packages field missing or empty`

Your pnpm version is older than 10. Update it with npm install --global pnpm, then run pnpm install again.

`ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` or `ERR_PNPM_NO_GLOBAL_BIN_DIR`

You tried to install a package globally with pnpm add -g before pnpm was set up for global packages. For the Laioutr CLI you do not need a global install: use pnpm rc:fetch inside the App Starter, or npx @laioutr/cli@latest. If you want global packages, run pnpm setup and open a new terminal.

Project configuration

`command not found: laioutr`

Use the CLI that ships with the App Starter: pnpm rc:fetch …. Anywhere else, run it with npx @laioutr/cli@latest <command>. See the CLI documentation.

`The Laioutr API rejected the request (400 Bad Request)` from `rc:fetch`

The project secret is wrong. Copy it again from project settings.

`The Laioutr API is currently unavailable (500 Internal Server Error)` from `rc:fetch`

Check the -p value first: an unknown organization or project slug currently produces this error too. Both slugs are in the Cockpit URL of your project.

`laioutrrc.json is missing` or `Cannot find module '../laioutrrc.json'`

The playground has no project to render. Fetch the configuration:

pnpm rc:fetch -p <organization-slug>/<project-slug> -s <project-secret>

`unexpected end of JSON input`

Your laioutrrc.json file is corrupted or incomplete. Delete it and fetch it again:

rm laioutrrc.json
pnpm rc:fetch -p <organization-slug>/<project-slug> -s <project-secret>

`laioutrrc.json lists … not installed` or `Could not load @laioutr-app/<name>. Is it installed?`

Your project uses apps that are not installed. Install them and start pnpm dev again. In the App Starter, add them as dev dependencies: pnpm add -D @laioutr-app/<name>. The startup banner marks each missing app as not installed. With Could not load …, frontend-core names only the first missing app, so repeat until pnpm dev starts.

Build and dev server

`Cannot find module './.nuxt/tsconfig.json'`

The generated .nuxt folder is missing or out of date. This happens after a fresh clone or a dependency update, before the first pnpm dev. ESLint then reports every import as unresolved, and tests or builds fail. Generate it:

pnpm dev:prepare

`Cannot find module '…/jiti@…/node_modules/jiti/node_modules/.pnpm/jiti@…'` or `Cannot load module. Please check dist`

The doubled path is misleading. The real cause: src/module.ts imports a package that is not installed at the top of node_modules. Add every package that src/module.ts imports to dependencies in package.json, and check that the project's .npmrc contains shamefully-hoist=true. Then run pnpm install again.

`… is not exported by "#imports"`

Two versions of the Laioutr core packages are installed at once — usually after adding an app that needs a newer core than your project. Check with:

pnpm why @laioutr-core/frontend-core

If it lists more than one version, move every Laioutr package to the current release together:

pnpm add -D @laioutr-core/frontend-core@latest @laioutr-core/core-types@latest @laioutr-core/canonical-types@latest @laioutr-core/devtools@latest @laioutr-app/ui@latest

`Using alternative port 3001`, `EADDRINUSE` or `EMFILE: too many open files`

An earlier dev server is still running and holds port 3000 and the file watchers. Nuxt then starts on another port, and the browser or Studio can still reach the old server. Find the processes that listen on port 3000 and stop them:

lsof -nP -iTCP:3000 -sTCP:LISTEN
kill <PID>

`JavaScript heap out of memory` during `pnpm dev:build`

A full production build needs more memory than Node.js allows by default:

NODE_OPTIONS=--max-old-space-size=8192 pnpm dev:build

Setup Local Development Environment

Create your first custom app