Troubleshooting & Best Practices

This page collects the most frequent symptoms on a WUIC installation, their real cause and the verified fix. Before digging into code, read the three diagnostic endpoints: most of the time the answer is there.

First diagnosis: three endpoints

Frequent symptoms

Lists show at most 20 records

The backend runs in Trial mode: license missing, expired or with an unauthorized fingerprint. LicenseStatus returns licenseValid=false with the reason in licenseReason (invalid_signature, machine_fingerprint_not_authorized, machine_fingerprint_missing, license_expired). Fix: see the Licensing page; after entering license-payload and license-signature restart the backend and check licenseValid=true.

A Pro feature opens the "access denied" page

The license tier does not include the feature (features in LicenseStatus): designer, workflow, reports, spreadsheet, pivot-grid and RAG chatbot are Professional. The route guard requireFeature blocks access on Developer.

"RAG server unreachable" / RAG offline

• status=not-initialized without lastError: the engine is downloading models and index (~4.5 GB, 1-5 min) or loading them (warm-up ~30 s). Wait for the in-app notification.
• lastError set: download failed (CDN unreachable, disk full) or rag-engine/WuicRagEngine.dll missing. Check rag-engine-models-url, disk space and rag-engine-dll-path.
• rag-use-dotnet-engine=false without a Python server: the controller bridges to 127.0.0.1:8765, which does not exist. Set the key back to true.
• Slow queries (15-25 s): normal on CPU. With an NVIDIA GPU check CUDA 12.x + cuDNN 9 and rag-engine-cuda-path.
• Slow cold start on Windows: add rag-engine/artifacts/ to the antivirus exclusions (Defender scans vectors.npy on every start).

Metadata changes are not visible

The runtime metadata cache is still valid. After direct SQL changes to the _metadati__* tables call MetaService.invalidateMetadataRuntime with the explicit body {"clearAll":true} (without a body the flush is partial) and check that projectMetadataVersion changes via MetaService.getProjectMetadataVersion. Changes made from the designer or the chatbot invalidate by themselves.

Every query longer than a few seconds fails

AppSettings.autoGeneratedQueryTimeout is the timeout in seconds of the auto-generated queries: a value that is too low (e.g. 1) fails any non-trivial list. Set it back to 30 or more; the key is hot-reloaded.

"Optimistic concurrency error" on save

The record was modified by another user or process after it was read: reload it and reapply the change. If it appears on every write, check that there are not two backends on the same database (typical in test: one started by hand plus the dispatcher's). See Optimistic Concurrency.

The session is closed by itself (session_replaced)

The framework enforces a single session per user: a second login of the same user replaces the first one. If it happens without a second login, again: two backends on the same metadata DB.

The first-run wizard reappears on every start

AppSettings.firstRun is still "true" in the appsettings.{Environment}.json read by the running host (mind the active environment: Development vs Production). The wizard sets it to false at the end of provisioning; if the file is not writable by the process, it stays true.

A lookup shows [object Object]

mcuilookupdata_value_field, mcuilookupdata_text_field and mc_ui_grid_*_id_field must hold the friendly column name (= mc_nome_colonna): they are keys into the response JSON. Fields that emit SQL (md_nome_tabella, mc_real_column_name) must instead carry the exact physical case of the schema.

The query-string filter is ignored

URLs to <route>/List accept filterInfo=..., not filter=....

Routes with spaces are not found

Metadata routes may contain significant spaces: do not trim() or normalize them when building or comparing them.

Error 10316 during tutorial scaffolding

SQL Server 2017, or Express with its RAM cap, under spatial load. Requirement: SQL Server 2019+; for local dev use Developer Edition or LocalDB.

Linux behind a reverse proxy: wrong port or scheme in URLs

The nginx vhost must forward host and scheme: proxy_set_header Host $http_host; and proxy_set_header X-Forwarded-Proto $scheme;. Upgrades do not rewrite an existing vhost.

Reports not generated on Linux

Versions before 1.7.0 handled fonts through a Windows-only graphics library: update the package.

Quick checklist

1. Network tab: request and response of the failing MetaService.* call. A wrong JSON key does not return 400: the backend uses defaults and the diagnosis is skewed.

2. Route md_props_bag and column configuration (mc_ui_column_type, lookups, hide flags).

3. LicenseStatus, FirstRunStatus, Rag/Health as above.

4. The appsettings.{Environment}.json of the environment that is actually active.

5. One backend per database.

Best practices

• Primary keys and indexes on exposed tables: auto-generated filters, paging and sorting rely on them.
• Change metadata from the designer or the chatbot when you can: cache invalidation is automatic.
• Enable AppSettings:enablePerformanceInspector to measure fetch and render per route (average, p95, max) before optimizing by guesswork.
• After an upgrade compare appsettings.json with the package template: new keys have conservative defaults, but the comparison avoids surprises.
• Use typed exceptions for application errors: see Custom Exception Handling.