Error catalog

Troubleshooting

Find the message the CLI printed, then apply the fix. Values in <angle brackets> differ per run. Start with npx create-fsd-architecture@latest doctor: it checks Node.js, Git, your package manager, and the project layout in one go. Exit codes are listed in the CLI reference.

Node.js and toolchain

Node.js >=22.12.0 is required by the CLI (found 20.x). Upgrade Node.js to satisfy the supported runtime range before running this command.

Cause: The running Node.js is older than the CLI or the selected framework needs. Nuxt and SvelteKit need 22.22.2 or later.
Fix: Install a supported Node.js (for example with nvm install 22), open a new shell, and check node --version. See Compatibility for each framework.

Unsupported package manager "<name>".

Cause: --package-manager or fsd.config.json names something other than npm, pnpm, yarn, or bun.
Fix: Use one of npm, pnpm, yarn, or bun. doctor also reports when the installed version is below the minimum.

Creating a project

--framework is required when using --yes (for example, --framework react-vite).

Cause: --yes skips every prompt, including the template choice.
Fix: Add --framework react-vite, nextjs, vue-vite, nuxt, or sveltekit, and pass a project name.

A project name is required when using --yes.

Cause: Non-interactive mode cannot ask for the name.
Fix: Pass the name first: create-fsd-architecture my-app --framework react-vite --yes.

"<name>" already exists. Re-run with --force to replace it.

Cause: The target directory is not empty.
Fix: Choose another name, or pass --force to replace it. --force rolls back automatically if creation fails.

Project directory must be created inside the current directory.

Cause: The name contains .. or an absolute path.
Fix: cd to the parent folder first and pass a plain or nested relative name such as apps/web.

Cannot download template <repo> at pinned commit <ref>: <reason>

Cause: The CLI fetches the pinned template commit with git over HTTPS, and Git is missing or github.com is unreachable (offline, proxy, or firewall).
Fix: Check that git --version works and that you can reach https://github.com. Behind a proxy, set git config --global http.proxy, then retry.

Dependency installation failed; project changes were rolled back.

Cause: The package manager exited with an error, usually network, registry auth, or an engines mismatch.
Fix: Read the package manager output printed below the message. Retry with --no-install to inspect the project, then install manually.

Generating slices

Invalid type "<type>". Allowed types: feature, entity, widget, page.

Cause: The first argument after -g is not a layer the generator supports.
Fix: Use feature, entity, widget, page, or shared. app and shared accept only --segments.

"<path>" already exists. Re-run with --force to replace it.

Cause: A slice with that name is already in the layer.
Fix: Pick another name or pass --force for a single slice. Review with --dry-run first.

Batch generation does not support --force; replace one reviewed slice at a time.

Cause: Several names were passed together with --force.
Fix: Run one command per slice you intend to overwrite.

Slice name must start with a letter after normalization (for example, product-123).

Cause: The name starts with a digit or contains only symbols.
Fix: Use letters, numbers, and dashes, starting with a letter.

Place generate options after --generate.

Cause: Flags such as --dry-run came before -g.
Fix: Write -g <type> <names...> first, then the flags.

Structure-only segments

--root requires --segments (structure-only generation).

Cause: --root only applies to the structure-only mode.
Fix: Add --segments ui,api (or the segments you need).

Segments must be comma-separated lowercase names (for example ui,api,model).

Cause: Segments were passed with spaces or uppercase letters.
Fix: Pass one argument: --segments ui,api,model.

--segments cannot be combined with --force or --auth-provider.

Cause: Structure-only mode never overwrites files and generates no auth code.
Fix: Drop --force and --auth-provider from structure-only commands.

For shared/app use --segments without slice names.

Cause: shared and app have no slices.
Fix: Run -g shared --segments ui,lib without a name.

Refusing symlink path: <path>

Cause: A target folder is a symlink; the CLI refuses to write through it.
Fix: Replace the symlink with a real directory or choose another --root.

Supabase auth adapter

--auth-provider supabase is only valid for feature auth.

Cause: The flag was used with another slice.
Fix: Run -g feature auth --auth-provider supabase.

Configure the browser Supabase Auth client before submitting a form.

Cause: Generated forms ran before configureSupabaseAuth(client) was called.
Fix: Call configureSupabaseAuth with a browser client at app start. See Feature status for the setup snippet.

check, doctor, and architecture checks

Install steiger and @feature-sliced/steiger-plugin in this project before using --architecture. No packages are downloaded automatically.

Cause: check --architecture runs the project's own Steiger.
Fix: npm install -D steiger @feature-sliced/steiger-plugin, add a Steiger config, and run the check again.

Steiger architecture validation failed (<status>).

Cause: Steiger found layer or public-API violations.
Fix: Fix the reported imports, or adjust the rules in your Steiger config. The command exits non-zero so CI fails.

Unsupported fsd.config.json schemaVersion: <version>.

Cause: The config was written by a newer CLI.
Fix: Run the latest CLI with npx create-fsd-architecture@latest.

Upgrades

--check cannot be combined with --yes or --no-install.

Cause: --check is read-only and never applies changes.
Fix: Use upgrade --check in CI and upgrade --yes locally.

Upgrade failed: <reason> Affected source, configuration, manifest, and lockfile paths were rolled back.

Cause: A migration step or the dependency install failed.
Fix: Nothing was left half-applied. Fix the reason shown, review upgrade --dry-run, and apply again.

upgrade --check exits with code 3

Cause: CLI-owned files were customized, so the plan has conflicts.
Fix: Run upgrade --dry-run to list the conflicting files and resolve them manually.

Still stuck?

Open an issue on GitHub with the full command, the output, and the result of doctor.