Troubleshooting#
Warning
Project Neo is currently in 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 or duplicated @squirro/nextgen-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 and a missing env.d.ts file. A stale core package is reported with the npm install command to run, but is not upgraded automatically.
Getter Is Not a Function Error#
Symptom: The browser console shows an error like:
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/nextgen-core package contains a stale pre-built host. Remove and reinstall it:
# In your bundle:
rm -rf node_modules/@squirro/nextgen-core
npm install
neo-ui dev
Quick diagnosis: find missing packages
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/nextgen-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:
✗ 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):
lsof -i :3001
To stop it if safe to do so:
kill $(lsof -ti :3001)
To change the port in your project:
neo-ui config
The same applies to DEV_PROXY_PORT (default 5555).
CORS Errors in the Browser Console#
Symptom:
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/nextgen-core'.
Fix:
npm install
If the error persists, the package copy may be corrupted. Remove and reinstall:
rm -rf node_modules/@squirro/nextgen-core
npm install
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.jsonLocal 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:
[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:
[extensions] ════════════════════════════════════════════════════════════
⚠ VERSION MISMATCH
Extension built against nextgen-core@1.2.0, host is running @1.3.0. Compatibility is not guaranteed.
[extensions] ════════════════════════════════════════════════════════════
What it means: The bundle was built against a different version of @squirro/nextgen-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:
npm install @squirro/nextgen-core@latest
neo-ui build
# then redeploy
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?
ls -la .env
If missing, run neo-ui config to create it, or create .env manually with:
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:
chmod 600 .env
Check 2: Are you running ``neo-ui dev`` from inside the project directory? Verify that src/manifest.ts exists:
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:
┌──────────────────────────────────────────────────────────┐
│ │
│ ⚠ NextGen Core — Dependency Version Mismatch │
│ │
│ The following dependencies don't match the versions │
│ required by NextGen 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/nextgen-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:
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 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:
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:
neo-ui config
# Select "API credentials"
Different 0.x minor: pre-1.0 minors are breaking#
Your bundle was built against a different minor version of @squirro/nextgen-core than the host is running. For pre-1.0 releases, minor version changes are breaking. Choose one of the following options:
# 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:
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>.