Troubleshooting & FAQ

Cause: Blazor WASM cannot reach the API, or cached WASM files are stale.

Fix:

1. Confirm API is running: open https://localhost:7149/api/system/version
2. Check apps/Cognitix.WebApp/wwwroot/appsettings.json — ApiBaseUrl must match API URL (trailing slash required)
3. Hard refresh: Ctrl+Shift+R
4. DevTools → Application → Clear site data, then reload
5. Delete bin and obj under WebApp, rebuild, run again

Common message: JWT signing key is missing or too short

Set Jwt:Key in API appsettings.json with at least 32 characters, or set environment variable COGNITIX_JWT_KEY.

Also verify Jwt:Issuer and Jwt:Audience are not empty.

Run once: dotnet dev-certs https --trust

Or use the HTTP profile (update CORS origins and ApiBaseUrl to http:// ports consistently).

Example: blocked by CORS policy: No 'Access-Control-Allow-Origin' header

Add your WebApp origin to API appsettings.json:

"Cors": {
  "AllowedOrigins": [
    "https://localhost:7019",
    "http://localhost:5281"
  ]
}

Origin must match exactly — scheme (https vs http) and port included.

1. API running? Test /api/system/version in browser
2. ApiBaseUrl in WebApp matches API base address
3. Firewall not blocking local ports 7149 / 7019
4. If using IIS or reverse proxy, confirm published API URL is updated in WebApp config

Use the admin account created in Setup Wizard Step 2. There is no default production password shipped with the product.

Ensure Step 1 (database) completed successfully before Step 2. See Database/SEED-DATA-NOTES.md.

1. Jwt:Issuer / Jwt:Audience should match your API public URL
2. Clear browser storage (localStorage) and log in again
3. Check token expiry — default 60 minutes in AccessTokenMinutes
4. Logout and verify refresh token is rejected (expected security behaviour)

Rate limiting applies to login endpoint. Wait ~15 minutes or reset via database/admin procedure in development.

No for normal install or updates. Use Setup Wizard Step 1 Continue — the system prepares the database automatically.

Support/recovery only: Database/apply-migrations.ps1 — see Database/MIGRATION-NOTES.md.

dotnet tool install --global dotnet-ef

Restart terminal. Buyers do not need this for Setup Wizard install.

Before Setup Wizard Step 1: API logs may show “Cannot open database” — this is normal until you complete Step 1.

1. Database service is running (SQL Server / PostgreSQL / MySQL)
2. In Step 1, engine + server host/port/credentials match your server
3. Login has permission to create/alter tables (and create database if it does not exist)
4. You entered the database name you want — there is no required name CognitixERP
5. PostgreSQL: use host 127.0.0.1 when DB is on the same VPS; check pg_hba.conf allows the API user
6. MySQL: confirm port (often 3306) and that the user can create schemas

CognitixERP uses 12 EF Core DbContexts in one database. Normal buyers use Setup Wizard Step 1 — not manual scripts.

If Step 1 fails: drop the entire database you chose in the wizard and retry, or use Database/apply-migrations.ps1 (support).

After setup is complete, API restart auto-applies pending schema updates on startup.

Database was partially set up from a previous attempt. Drop the entire database name you used in Setup Wizard Step 1 and run Step 1 again.

Copy or download the JSON from the Setup Wizard completion screen into:

apps/Cognitix.WebApp/wwwroot/appsettings.json

Example:

{ "ApiBaseUrl": "https://localhost:7149/" }

Trailing slash required. Must match the API URL from Step 1. See Installation Guide §7.

Development: With Licensing:SkipInDevelopment=true and ASPNETCORE_ENVIRONMENT=Development, the 14-day trial can start locally. Purchase-code activation still calls CognitiveCircle and rejects invalid codes.

Production: Requires SkipInDevelopment=false, internet access to https://api.cognitivebd.com, and valid product ApiKey / HmacSecret.

SSL errors in development usually mean the API is not running in Development mode or skip is disabled. Cognitix ERP Linux samples use Kestrel on 127.0.0.1:5100 (not 5000).

1. nginx must proxy /uploads/ (and preferably /api/uploads/) to the API — see deploy/hetzner/nginx-site.conf.example
2. In Setup Wizard, API URL must be the site origin without /api (e.g. https://yourcompany.com)
3. Direct test: curl -I https://yourcompany.com/uploads/logos/YOUR_FILE.png should return 200 and an image content type

The buyer package uses DLLs under lib/Cognitix.Licensing/. Commit those three DLLs and publish with -p:BuyerBuild=true (the sample deploy.yml detects this automatically).

In production (not dev skip):

• GET /api/license/status returns Active or Trial — not DevelopmentSkipped
• SQL: LicensedItemId, LicensedItemTitle, PurchaseCodeLast4 saved in Licensing.InstallationSettings
• CognitiveCircle Admin → Licenses shows the buyer row

app.example.com and example.com are separate domains. Regular license allows one active domain per purchase code.

Activate on the exact URL your users open in the browser. If you moved hosts, contact support for a domain reset (Regular) or use Settings → License on the correct URL.

If CognitiveCircle marks your activation Inactive/Revoked, CognitixERP locks on the next heartbeat or Re-verify (typically within 24 hours, or immediately if you click Re-verify).

72-hour offline grace applies only when CognitiveCircle is unreachable (network/server outage) — not when the server explicitly reports revoked.

With a previously verified Active license, ERP allows up to OfflineGraceHours (default 72) while CognitiveCircle cannot be reached. After that, re-verify when connectivity returns.

Configure SmtpSettings in API appsettings.json or optional smtp.settings.json next to the API project.

• Use valid host, port, SSL setting for your provider
• Gmail requires app password or OAuth — not plain account password in many cases
• Test from Settings → Email in the WebApp after SMTP is configured

Never commit real SMTP passwords to source control.

Role & Permission system hides pages the user cannot access. Assign correct role in User Management or log in as admin.

Branch-scoped users only see data for their assigned branch.

Toggle theme from user profile/preferences. If custom CSS was added, ensure it uses theme CSS variables (--cgx-*) from shared stylesheets.

Decimal places come from Currency Management (e.g. JPY = 0, KWD = 3). Configure currency in Financials → Currency; do not hardcode N2 in custom code.

Only your real WebApp URL(s), e.g. https://yourcompany.com. Remove all localhost entries in production appsettings.Production.json or environment variables.

Add every hostname users open in the browser (including www aliases). Do not use wildcard *.

"Cors": {
  "AllowedOrigins": [ "https://yourcompany.com" ]
}

Environment variable: Cors__AllowedOrigins__0=https://yourcompany.com

Full steps: Production Deployment Guide §5.

• Set strong COGNITIX_JWT_KEY via environment variable (32+ chars) — do not commit keys to source control
• For same-origin deploy, set Jwt:Issuer and Jwt:Audience to the public site origin (same as ApiBaseUrl without trailing slash), e.g. https://yourcompany.com
• Always use HTTPS in production
• Use the admin account created in Setup Wizard Step 2 — change password after first login

COGNITIX_JWT_KEY=<generated-key>
Jwt__Issuer=https://yourcompany.com
Jwt__Audience=https://yourcompany.com

Full steps: Production Deployment Guide §4.

See Please Contact us below, or email support@cognitivebd.com with:

• CodeCanyon purchase code
• CognitixERP version (GET /api/system/version)
• Steps to reproduce + screenshots / API log excerpt
• OS, .NET version (dotnet --version), database engine (SQL Server / PostgreSQL / MySQL)

Included support: 6 months from purchase.