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 extensions and how to resolve them.
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 extension 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 extension project:
rm -rf node_modules/@squirro/nextgen-core
npm install
nextgen 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#
Symptom:
✗ Extension port 3001 is already in use.
Set a different port in .env (EXTENSION_PORT=<port>) or run `nextgen config`.
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:
nextgen 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 extension dev server by default. That error should not occur with a standard nextgen dev setup.
If that error appears in development:
Verify you opened
http://localhost:5555(not 3001) in your browser.Restart
nextgen dev. The extension server may not have started correctly.
In production, extensions 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/<project-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 project 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/<project-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 extension was built against a different version of @squirro/nextgen-core than the one running. The extension still loads and will usually work, but there may be subtle incompatibilities.
Fix: Rebuild and redeploy the extension against the current core version:
npm install @squirro/nextgen-core@latest
nextgen 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 nextgen 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 ``nextgen 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 nextgen dev or nextgen 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 extension 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 extension.
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. Extensions can still run with mismatched versions, but you may encounter unexpected behavior at runtime.
Cannot Update Manifest Error#
Symptom: nextgen create dashboard or nextgen 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 Extension Manifest page.