Skip to main content

Troubleshooting

Common framework issues and their solutions. For Builder-specific problems (compilation, dependencies, deployment), see Builder Troubleshooting.

LCP / Connector Errors​

"Method not found" or empty response from @Extern call​

Symptom: Frontend connector call returns null, throws "method not found", or silently fails.

Causes and fixes:

  1. Missing ForceCompile entry — The backend class must be imported in ForceCompile.ts. If not, the class is never compiled into the bundle and LCP cannot resolve it.

    oidis build dev   # Rebuilds and auto-generates ForceCompile entries

  2. Wrong namespace in getServerNamespaces() — The frontend connector's namespace string must exactly match the backend class path. Check for typos:

    // Frontend connector
    map.set(WebServiceClientType.HUB_CONNECTOR, "Io.Oidis.YourProject.Utils.DataManager");
    //                                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    // Must match the actual filesystem path: source/typescript/Io/Oidis/YourProject/Utils/DataManager.ts

  3. Method not decorated with @Extern() — Verify the backend method has the decorator.

  4. AuthManager not registering the method — New @Extern methods must be registered in the AuthManager. See Authorization Flow.

"Unauthorized" or 403 on @Extern calls​

Symptom: LCP call is rejected with an authorization error.

Causes and fixes:

  1. Method not in permission category — Register it in AuthManager:

    this.generateAuthMethodsFrom<YourConnector>(AuthMethodCategory.ONLY_FOR_AUTHORIZED_USERS,
        YourConnector, ($proto : YourConnector) => [$proto.YourMethod]);

  2. User lacks group permission — Check if the method is restricted to a specific system group via addSystemPermissions(). See System Groups.

  3. Session expired — Check browser DevTools network tab for 401 responses. The session may have timed out.

Database Issues​

Models return empty results​

Symptom: Find() returns an empty array or fewer results than expected.

Causes and fixes:

  1. Soft-deleted records filtered out — If you're filtering { deleted: { $ne: true } } but the records were hard-deleted with Remove(), they won't exist at all. If you're NOT filtering, soft-deleted records will appear.

    warning

    Find() does not automatically exclude soft-deleted documents. Always include { deleted: { $ne: true } } in your filter unless you specifically need deleted records.

  2. Wrong database — Verify commons.jsonp points to the correct database. Check the database name in the MongoDB shell:

    mongosh --port 27018
    > show dbs

  3. Collection name mismatch — The @Entity("collectionName") decorator must match the actual MongoDB collection. Collection names are case-sensitive.

"Cannot read properties of null" on model fields​

Symptom: Accessing a model property throws a null reference error.

Cause: The model was found but the field doesn't exist in the document (e.g., added after existing records were created).

Fix: Use @Property({ default: ... }) to provide defaults, or check for null before accessing:

const value = record.SomeField ?? "default";

Development Workflow​

Hot reload not picking up changes​

Symptom: oidis dev is running but changes don't appear in the browser.

Causes and fixes:

  1. Wrong file type — oidis dev watches TypeScript and SCSS files. Changes to JSONP config, HTML templates, or static assets require a full rebuild:

    oidis build dev

  2. Compilation error — Check the terminal running oidis dev for TypeScript errors. A failed compilation means no new output.

  3. Browser cache — Hard refresh with Ctrl+Shift+R (or Cmd+Shift+R on macOS).

Stale artifacts after branch switch​

Symptom: Build errors or unexpected behavior after switching branches or pulling large changes.

Fix: Run a clean rebuild:

oidis rebuild   # Equivalent to: clean + build dev

If the issue persists, reinstall dependencies:

oidis install   # Re-clones all dependencies from Git
oidis rebuild
danger

oidis install deletes the entire dependencies/ directory before reinstalling. Commit or sync any changes in dependencies/ before running this command.

Lint errors blocking commit​

Symptom: Pre-commit hook rejects the commit with lint violations.

Fix: Run the linter to see exact violations, fix them, then commit again:

oidis test lint

Common violations:

  • Missing space before/after type colon (name: string → name : string)
  • Single quotes instead of double quotes
  • Missing .js extension in imports
  • Missing copyright header
  • Wrong member ordering (fields before methods)

See Code Review Checklist for the full list.

Authentication​

Login fails with correct credentials​

Causes and fixes:

  1. Account locked — Too many failed attempts. Check authManagerWorker.singInCheck.numberOfTries in commons.jsonp. The account auto-unlocks after the configured interval.

  2. Account deactivated — The activation check worker may have deactivated the account. Check the Hub admin panel.

  3. Multi-session disabled — If authManagerWorker.multiSessionEnabled is false, logging in from a second browser/device invalidates the first session.

SSO redirect loop​

Symptom: Browser redirects between the login page and the OAuth provider in a loop.

Causes and fixes:

  1. Redirect URI mismatch — The redirectUri in authProviders.google must exactly match the URI registered in the Google Cloud Console.

  2. Cookie domain mismatch — Check that the domain setting in commons.jsonp matches the actual server hostname. Cookies set for a different domain are silently ignored by the browser.

  3. Strict secure cookies on HTTP — If authManagerWorker.strictSecureSSOcookies is true but the server runs on HTTP (no TLS), the browser rejects the cookies. Disable this flag for local development.

Email​

Emails not being sent​

Symptom: Registration, password reset, or notification emails are not delivered.

Causes and fixes:

  1. Mail engine disabled — Check sendmail.enabled in commons.jsonp or in Application Settings (Hub GUI).

  2. Queue not processing — The async loop may not have started. Check sendmail.fetchTick — if set to 0, the loop is disabled.

  3. Recipient on blacklist — Addresses in sendmail.blackList are silently excluded. Check the list in Application Settings.

  4. SMTP connection failed — Check SMTP host, port, and credentials in commons.jsonp. Test connectivity from the server.

Common Error Messages​

ErrorLikely causeFix
Target folder has not been recognizedWrong directory or missing package.conf.jsonpcd to project root
Cannot find module "@io-oidis-..."Dependencies not installedRun oidis install
ExternInvokeEnabled is falseConnector disabled programmaticallyCheck if ExternInvokeEnabled(false) is set
Multiple internal setting structures foundDuplicate appSettings documents in DBRemove duplicates, keep one
strict email check failedDuplicate email during registrationEnable strictEmailCheck or check existing accounts
this.events.Subscribe is not a functionA tab id or member named events overwrites GuiCommons.eventsRename it — see GUI Pitfalls
Types have separate declarations of a private property '…'Panel/dialog/row member reuses a private CORE member nameRename the member — see GUI Pitfalls
Property 'Text' does not exist on type 'Button'Button has no Text()Use Content()

See also: Builder Troubleshooting | Oidis Builder Quick Start | LCP & RPC | Authentication