> ## Documentation Index
> Fetch the complete documentation index at: https://www.lettercamp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI troubleshooting

> Resolve Lettercamp setup, preview, deployment, and domain connection problems.

Find the symptom you see below and follow its recovery steps. For command syntax,
see the [CLI reference](https://www.lettercamp.com/docs/cli.md).

> [accordion] A component works locally but Cloud cannot resolve an import
>
> Run [`npx lettercamp check`](https://www.lettercamp.com/docs/cli/check) to see import problems with file
> locations and fixes. Replace `#blog/...` and other project aliases with relative
> paths. Use CSS or Sass stylesheets, and replace external
> packages such as `react-icons` with local components or inline SVG. Installing
> a package locally does not install it on Cloud. See
> [supported imports](https://www.lettercamp.com/docs/react-components.md#supported-imports).

> [accordion] Cloud requires remotely hosted fonts or assets
>
> With current CLI deployments, files in `public/` are uploaded with their paths
> intact. Use [`npx lettercamp check`](https://www.lettercamp.com/docs/cli/check) to check your local source.
> For a build using `--remote-assets-only`, set
> `design.typography.localFonts` to `false` and use hosted media URLs. See
> [Cloud assets](https://www.lettercamp.com/docs/publishing/deploy.md#local-images-and-cloud-assets).

> [accordion] Setup created the files but npm install failed
>
> Open the created directory and run `npm install`, then `npm run dev`.
> Do not repeat setup in that folder: it is no longer empty. The same steps
> apply when you deliberately used `--no-install`.

> [accordion] A font is missing in the local preview
>
> The starter includes local files for Inter, Geist, Geist Mono, Instrument
> Serif, and EB Garamond. To use another catalog font, set
> `design.typography.localFonts` to `false` so it loads from the CDN, or
> provide the required local files. See [Local fonts](https://www.lettercamp.com/docs/design/typography.md#local-fonts).

> [accordion] Deployment stopped or the connection dropped
>
> Run `npx lettercamp deploy` again from the same folder. It resumes the saved
> deployment. If you edited local files after the interrupted upload, deploy
> once more after it finishes to publish those edits.

> [accordion] The hosted source changed
>
> Someone changed the source through another deployment or the web editor.
> Deployment stops before uploading. Review the changes in Cloud, or run
> `npx lettercamp deploy --new` to publish this folder as a separate site.
> The CLI does not offer to overwrite those remote edits.

> [accordion] This folder's deployment site is unavailable
>
> Run `npx lettercamp whoami` to check the account, and sign in with the correct
> account if needed. Deployment never selects another existing site as a
> fallback. To create a new destination, run `npx lettercamp deploy --new`.

> [accordion] A domain or subfolder is still pending
>
> Run `npx lettercamp domain` to resume. For hostnames, check every printed DNS
> record. For subfolders, deploy the proxy rules on your existing website and
> preserve the entire subfolder path. Its HTTPS verification URL must reach
> Lettercamp directly, without a login or redirect.

> [accordion] Node.js version is too old
>
> Upgrade to Node.js 22.23.4 or newer, then run `node --version` in your current
> terminal to confirm the active version. Reinstall the CLI if your Node.js
> version manager keeps separate global packages for each version.

> [accordion] The lettercamp command is not found
>
> Confirm that the global install succeeded and your package manager's global
> executable directory is on your `PATH`. You can also use
> `npx lettercamp@latest dev` from your publication directory.

> [accordion] The destination directory is not empty
>
> Choose a new directory for `npx lettercamp new`. If you already have a publication,
> open its directory and run `npx lettercamp dev` to preview it.

> [accordion] The preview cannot find settings.json or pages
>
> Run `npx lettercamp dev` from the publication root, where `settings.json` and `pages/`
> are located. Make sure `settings.json` contains valid JSON.

> [accordion] Port 3000 is already in use
>
> The CLI tries `8888`, then `4000`, `5000`, `6000`, `7000`, and `8000`. If all
> are busy, it searches from `3001` upward. Open the printed preview URL, or use
> `npx lettercamp dev --open` to open it automatically. Use `--port` to override this
> order and search sequentially from your chosen port.

> [accordion] A global install or update fails with a permissions error
>
> Use a Node.js version manager or configure npm's global installation directory
> so your user can write to it. To run the CLI without a global installation,
> use `npx lettercamp@latest` followed by the command you need.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.