<!-- Source: https://docs.squirro.com/en/latest/technical/neo/dev-guide/troubleshooting.html -->
# Troubleshooting

> **Warning**
>
> Project Neo is currently in [Technical Preview](../../../a-z/squirro-glossary.md#term-Technical-Preview). Features described in this section may change before general availability.

This page covers common issues encountered when developing Project Neo bundles and how to resolve them.

> **Tip**
>
> Before working through the sections below, run `neo-ui doctor`. It checks for most of these problems, including a stale GitHub Packages line in the project or user `.npmrc`, a stale or duplicated `@squirro/neo-core` package, a React version mismatch, a missing `.env` or `src/env.d.ts` file, and an expired API token, and it prints the fix for each. Run `neo-ui doctor --fix` to auto-heal the safe issues, such as a duplicate or missing core package, a missing `env.d.ts` file, and the stale registry line in the project `.npmrc`. A stale core package is reported with the `npm install` command to run, but is not upgraded automatically.

## Install Fails with an Error Naming npm.pkg.github.com

**Symptom:** `npm install -g @squirro/neo-ui`, or `npm install` inside a bundle, fails with an `E404`, `ETARGET`, or `E401` error that names `npm.pkg.github.com`, asks for a GitHub token, or reports that a `@squirro` version cannot be found.

**Cause:** the packages moved from GitHub Packages to the public npm registry. Nothing has to be configured for the new location, but an old `@squirro:registry=https://npm.pkg.github.com` line in an `.npmrc` still redirects every `@squirro` request to the old registry, and a scoped registry setting takes precedence over every other registry setting. Bundles created before the move have that line committed in their project `.npmrc`, and older setup instructions had you add it to `~/.npmrc` as well.

**Fix:** find the line in both places, delete it, then reinstall:

```bash
grep -n 'npm.pkg.github.com' .npmrc ~/.npmrc   # Shows the lines to delete
npm install
```

If the project `.npmrc` contained nothing else, delete the file and commit the removal so that your teammates stop hitting the same error. `neo-ui doctor --fix` removes the line from the project `.npmrc` for you. A GitHub personal access token is no longer needed for anything. Revoke any token you created only for package access.

## Cannot Find Module @squirro/nextgen-core after an Upgrade

**Symptom:** the build or the editor reports that `@squirro/nextgen-core` cannot be found, or `neo-ui doctor` reports that the package was renamed.

**Cause:** `@squirro/nextgen-core` became `@squirro/neo-core` in September 2026. A bundle that still imports the old name, or whose `node_modules` holds only the old package, is on the pre-rename line.

**Fix:** run the upgrade. It renames the dependency and rewrites the imports, the CSS `@import`, `biome.json`, `tsconfig.json`, `CLAUDE.md`, and the `NEXTGEN_CORE_VERSION` define:

```bash
neo-ui upgrade
neo-ui build
```

For the full migration, see the [Migrating from nextgen to neo-ui](migrating-from-nextgen.md#neo-extensions-migrating) page.

## Bundle Dashboards Not Appearing in the Sidebar

**Symptom:** The sidebar shows no custom entries after starting `neo-ui dev`.

**Check 1: Is the bundle server running?**

Open `http://localhost:3001/mf-manifest.json` in your browser. If it returns a 404, a connection refused error, or times out, the bundle dev server is not running.

Restart the dev server:

```bash
# Stop any running neo-ui dev process (Ctrl+C), then:
neo-ui dev
```

**Check 2: Are there dashboards in the manifest?**

Open `src/manifest.ts` and verify the `dashboards` array is not empty:

```typescript
dashboards: [
  // at least one entry here
],
```

If it is empty, add a dashboard:

```bash
neo-ui create dashboard MyDashboard
```

**Check 3: Did the browser receive the manifest?**

Open browser DevTools, go to the Network tab, and filter by `mf-manifest.json`. Confirm a 200 response with your manifest content.

## Getter Is Not a Function Error

**Symptom:** The browser console shows an error like:

```text
TypeError: getter is not a function
    at Object.<anonymous> (consumes.cjs:42)
```

The page may show a blank dashboard or an error boundary message.

**What it means:** The bundle expects a shared library (React, React Router, and so on) from the host, but the host did not provide it. That indicates a Module Federation shared scope mismatch.

**Most common cause:** The `@squirro/neo-core` package contains a stale pre-built host. Remove and reinstall it:

```bash
# In your bundle:
rm -rf node_modules/@squirro/neo-core
npm install
neo-ui dev
```

**Quick diagnosis: find missing packages**

```bash
node -e "
const pkg = require('./package.json');
const fs = require('fs');
for (const dep of Object.keys(pkg.dependencies || {})) {
  if (!fs.existsSync('node_modules/' + dep)) console.log('MISSING:', dep);
}
"
```

If that script lists any packages, run `npm install` to restore them.

**If the error persists after reinstalling:** The issue may be a version mismatch between the host build embedded in `@squirro/neo-core` and the shared dependency configuration. Contact your Squirro platform administrator to confirm you are using the correct version of the core package.

## Port Conflicts

`neo-ui dev` auto-resolves a busy default or `.env` port to the next free port for the run. It prints a notice and leaves `.env` unchanged, so no action is required in that case.

A hard error occurs only when you request a specific port with `--port` or `--proxy-port` and it is already taken:

```text
✗ Bundle port 3001 is already in use.
  Free the port, pass a different one, or set BUNDLE_PORT in .env
```

To find the process using the port (macOS and Linux):

```bash
lsof -i :3001
```

To stop it if safe to do so:

```bash
kill $(lsof -ti :3001)
```

To change the port in your project:

```bash
neo-ui config
```

The same applies to `DEV_PROXY_PORT` (default 5555).

## CORS Errors in the Browser Console

**Symptom:**

```text
Access to fetch at 'http://localhost:3001/...' from origin 'http://localhost:5555'
has been blocked by CORS policy
```

In local development, CORS headers are included on the bundle dev server by default. That error should not occur with a standard `neo-ui dev` setup.

If that error appears in development:

- Verify you opened `http://localhost:5555` (not 3001) in your browser.
- Restart `neo-ui dev`. The bundle server may not have started correctly.

In production, bundles are served from the same origin as the host, so CORS does not apply.

## TypeScript Error: Cannot Find Module

**Symptom:** Red squiggles in your editor or `tsc` errors on `import ... from '@squirro/neo-core'`.

**Fix:**

```bash
npm install
```

If the error persists, the package copy may be corrupted. Remove and reinstall:

```bash
rm -rf node_modules/@squirro/neo-core
npm install
```

## SQUIRRO_API_URL Rejected as Not Using HTTPS

**Symptom:** the CLI refuses the instance URL with a message stating that the host must be reached over `https`.

**Cause:** the refresh token in `.env` is a long-lived credential and travels with every request the CLI and the dev proxy make. A plain `http://` instance URL is therefore refused unless the host is on your own machine or local network, such as `localhost`, a `.local` name, or an address in the `10.x` or `192.168.x` ranges.

**Fix:** use the `https://` URL of your instance, and run `neo-ui config` to change it. For an isolated test instance with no TLS at all, set `NEO_UI_ALLOW_INSECURE_HTTP=1` in the shell before running the command.

## TLS Errors from the Dev Proxy

**Symptom:** the dev proxy fails with a certificate error such as `UNABLE_TO_VERIFY_LEAF_SIGNATURE` or `SELF_SIGNED_CERT_IN_CHAIN`.

**Cause:** the dev proxy verifies the instance certificate the way a browser does. An instance behind a company CA fails verification until Node knows that CA.

**Fix:** point Node at the CA bundle in the shell, not in `.env`, because Node reads the variable at process start, before `.env` is loaded:

```bash
NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem neo-ui dev
```

For a throwaway instance on your own machine or local network, `NEO_UI_INSECURE_TLS=1` skips verification. It is ignored for public hosts. For more information, see the [Local Development](local-development.md#neo-extensions-local-development) page.

## rsbuild, biome, or tsc Is Not Installed Error

**Symptom:** `neo-ui dev`, `neo-ui build`, or `neo-ui deploy` reports that `rsbuild`, `biome`, or `tsc` is not installed in the project.

**Cause:** those commands run the tools from the `node_modules/.bin` directory of the bundle and do not download them on demand. The dependencies of the bundle are missing, or were installed without development dependencies.

**Fix:**

```bash
npm install
```

## API Calls Returning 401 Unauthorized

**Symptom:** Network requests to `/api/*` return 401. Dashboards show errors or empty data.

**Cause 1: Expired refresh token.** Tokens expire. Update it:

```bash
neo-ui config
# Select "API credentials"
```

**Cause 2: Wrong API URL.** Verify the URL in `.env` matches your Squirro instance exactly, including the tenant path if present:

```bash
neo-ui info
# Check the "API" line
```

**Cause 3: Token lacks permissions.** Your user account may not have access to the projects you are querying. Check with your Squirro administrator.

## Dashboard Shows a Blank Page or Error Message in Production

**Check 1: Is the manifest reachable?** Visit your manifest URL directly in a browser. It should return JSON.

- Platform deployment: `https://your-instance.example.com/v0/workspaces/<domain>/ui_bundles/<bundle-name>/dist/mf-manifest.json`
- Local bind-mount: `https://your-instance.example.com/extensions/mf-manifest.json`

**Check 2: Is the project configured?** For platform deployment, verify the project has `frontend.ui-bundle` set to your bundle name under Setup Space → Settings → Project Configuration.

**Check 3: Browser console errors.** Open DevTools and go to the Console tab. A bundle load failure appears as:

```text
[extensions] ════════════════════════════════════════════════════════════
  ✖  BUNDLE LOAD FAILED
  /v0/workspaces/<domain>/ui_bundles/<bundle-name>/dist/mf-manifest.json
  ...error message...
[extensions] ════════════════════════════════════════════════════════════
```

If you see that message, the bundle path is wrong or the upload did not complete.

## Version Mismatch Warning in the Console

**Symptom:** The browser console shows:

```text
[extensions] ════════════════════════════════════════════════════════════
  ⚠  VERSION MISMATCH
  Bundle built against @squirro/neo-core@3.17.0, host is running @3.17.1. Compatibility is not guaranteed.
[extensions] ════════════════════════════════════════════════════════════
```

**What it means:** The bundle was built against a different version of `@squirro/neo-core` than the one running. The bundle still loads and usually works, but there may be subtle incompatibilities.

**Fix:** Rebuild and redeploy the bundle against the current core version. Use `neo-ui upgrade` rather than installing the core package on its own, so that the core package and the CLI stay on matching versions:

```bash
neo-ui upgrade
neo-ui build
neo-ui deploy
```

## Browser Shows Loading Indefinitely

**Cause:** The dashboard component chunk failed to load, and the error boundary did not trigger.

**Check:** Open DevTools and go to the Network tab. Look for failed requests to JavaScript files from your CDN origin. Common causes:

- Files not deployed or the CDN not updated.
- CORS headers missing on the CDN.
- Incorrect manifest URL, with chunks referenced by wrong paths.

## Dev Server Crashes Immediately on Startup

**Check 1: Is there an ``.env`` file in the project directory?**

```bash
ls -la .env
```

If missing, run `neo-ui config` to create it, or create `.env` manually with:

```text
SQUIRRO_API_URL=https://your-instance.example.com
SQUIRRO_TOKEN=your-refresh-token
```

After creating the file, restrict its permissions so that only your user account can read it:

```bash
chmod 600 .env
```

**Check 2: Are you running ``neo-ui dev`` from inside the project directory?** Verify that `src/manifest.ts` exists:

```bash
ls src/manifest.ts
```

## Dependency Version Mismatch Warning on Build or Dev

**Symptom:** When running `neo-ui dev` or `neo-ui build`, a warning box appears:

```text
┌──────────────────────────────────────────────────────────┐
│                                                          │
│  ⚠  Neo Core — Dependency Version Mismatch               │
│                                                          │
│  The following dependencies don't match the versions     │
│  required by Neo Core. Mismatched versions can cause     │
│  runtime errors, broken UI, or subtle styling bugs.      │
│                                                          │
│  react                                                   │
│    installed:  18.2.0                                    │
│    required:   ^19.0.0                                   │
│    fix:        npm install react@^19.0.0                 │
│                                                          │
└──────────────────────────────────────────────────────────┘
```

**What it means:** Your bundle has installed dependency versions that do not match what `@squirro/neo-core` expects. Mismatched versions can cause runtime errors when Module Federation shares those libraries between the host and your bundle.

**Fix:** Run the `npm install` command shown for each mismatched package. The warning lists the exact version range required.

> **Note**
>
> That is a warning only. The build does not fail. Bundles can still run with mismatched versions, but you may encounter unexpected behavior at runtime.

## Cannot Update Manifest Error

**Symptom:** `neo-ui create dashboard` or `neo-ui remove dashboard` prints:

```text
Could not update manifest — unexpected format
```

The CLI uses pattern matching to update `src/manifest.ts`. If you have manually restructured that file in a way the CLI does not recognize, it cannot update it.

**Fix:** Ensure the manifest contains a `dashboards: [` line (matching exactly) and that dashboard entries use the standard format generated by the CLI. For the expected structure, see the [The Bundle Manifest](manifest.md#neo-extensions-manifest) page.

## Deploy Errors (neo-ui deploy)

This section covers errors reported by `neo-ui deploy`.

### Missing SQUIRRO_API_URL or SQUIRRO_TOKEN

The `.env` file is not configured. Run:

```bash
neo-ui config
```

### Token exchange failed: 401

The refresh token is expired or was minted on a different instance. Mint a new one in the Squirro UI under user profile → API tokens, then update `.env`:

```bash
neo-ui config
# Select "API credentials"
```

### Host version unavailable, instance predates version reporting

The instance has not been rebuilt with the version-reporting host. That is normal for older instances. `neo-ui deploy` proceeds with an `unknown` verdict and a warning, and no action is required.

### Incompatible Version Verdict

Your bundle was built against a major version of `@squirro/neo-core` that differs from the one the host is running, which the deploy gate treats as breaking. Choose one of the following options:

```bash
# Upgrade the bundle to match the host version
neo-ui upgrade
neo-ui deploy

# OR override the gate (only if you have confirmed compatibility)
neo-ui deploy --force
```

### dist/bundle-info.json is missing or malformed

The bundle was built with a bare `rsbuild build` instead of `neo-ui build`, so the deploy metadata was never stamped. Fix:

```bash
neo-ui build
neo-ui deploy --no-build
```

### Upload failed: 400 ui_bundle requires a dist/mf-manifest.json file

The bundle archive structure is wrong. Always use `neo-ui deploy`. Do not attempt to upload manually with `squirro_asset` unless you replicate the exact folder structure (`<name>/dist/mf-manifest.json`).

### Could not list projects (403)

The access token does not have permission to list projects on this instance, or the wrong tenant was derived. Verify that `SQUIRRO_API_URL` points to the correct instance (`https://your-instance.example.com`) and that the token was minted there.

### Setting frontend.ui-bundle failed

The bundle is uploaded but the project configuration was not updated. The error message includes the HTTP status. Common causes:

- **403**

  The token lacks project-config write permission.
- **404**

  The project ID was not found. Check that the project picker showed the right project.

Set the value manually under Setup Space → Settings → Project Configuration: `frontend.ui-bundle = <bundle-name>`.