Troubleshooting

Concrete symptoms and fixes for the issues you're most likely to hit when running EduNest LMS. Match the symptom, apply the fix, and check the relevant logs if it persists.

Common Problems

Database

Can't reach the database

EduNest connects to PostgreSQL through @neondatabase/serverless. If queries fail to connect:

• Verify DATABASE_URL host, user, password, and database name.
• Append ?sslmode=require for Neon and most managed Postgres providers.
• Confirm the database accepts connections from your host.

DATABASE_URL="postgresql://user:pass@host/db?sslmode=require"

Missing tables / "relation does not exist"

The schema is self-healing and is created during the wizard's Database step. If you imported a partial database or skipped the wizard, re-open /install and complete the Database step, which (re)creates the required tables idempotently.

Install Wizard

The wizard at /install doesn't appear (redirects away)

The installer gate keys off DATABASE_URL and the installed lock. If DATABASE_URL is already present in your environment, the app treats the database as configured and may skip straight past the early steps. If installation already completed, /install is closed. To re-run from scratch, point at a fresh database and clear the install lock.

The wizard can't save my settings on Vercel

Vercel's filesystem is read-only, so the wizard cannot write a .env file there. On read-only hosts the installer surfaces the values (such as DATABASE_URL and a generated JWT_SECRET) for you to add as Vercel project environment variables manually, then redeploy. The database schema is still created over the serverless connection.

Licensing

Public License Banner or admin License Gate is showing

This means the installation isn't in an active licensed state.

• Unactivated: enter your purchase code in the Install Wizard's License step or in Admin → License to activate this domain.
• Grace: the license server was unreachable on the last check. EduNest keeps running for a 14-day grace window; use Admin → License → Recheck once connectivity is restored to re-verify.
• Domain mismatch: the purchase code is active on a different domain. Deactivate it there (releases the seat), then activate here.
• Dev hosts (localhost, *.localhost, *.test, private LAN ranges) never require a license and never show the banner.

You can inspect the public, non-secret state at GET /api/license/status (returns state, type, entitlements, and a message — no purchase code or domain).

A premium add-on stays locked

A premium add-on is unlocked when either your product license carries an entitlement that covers it (*/all, the channel id, or the exact <channel>:<provider> key) or a valid per-add-on purchase code has been activated for it. If it's still locked:

• Confirm the entitlement is present in Admin → License (or GET /api/license/status).
• Or activate the add-on's purchase code in Admin → Add-ons.
• Remember the two-gate model: unlocking only makes the add-on available — you still flip the admin toggle to switch it on.
• Free providers (email:smtp, analytics:ga4, payments:cod/bank/paypal, storage:r2, video:youtube/vimeo) never require a key.

Storage

Uploads fail or images don't display

All uploads go server-side to Cloudflare R2 (or any S3-compatible storage) via the AWS S3 SDK — nothing is written to local disk in production.

• Verify your storage credentials in Admin → Settings (or the legacy R2_* environment variables): endpoint/account, access key, secret, bucket, and public base URL.
• Confirm the bucket exists and the key has read/write permission on it.
• If images upload but don't show, confirm the bucket's public URL / custom domain is correct and publicly reachable, and that the stored value is the public URL — not the raw object key.

Email

Emails not arriving (verification, reset, notifications)

EduNest sends mail with nodemailer over an SMTP integration configured in the database, not an env var. If mail isn't sending:

• Configure and activate SMTP in Admin → Settings → Email (SMTP is the free email provider and needs no license key).
• Verify the host, port, username, password, and from-address are correct.
• To avoid spam folders, set SPF/DKIM/DMARC records for your sending domain and use a verified from-address.

Build & Env

Build fails on deploy

• Node version: EduNest requires Node 20+. Ensure the host's Node version is set accordingly.
• Missing env var: confirm DATABASE_URL is present at build/runtime; on Vercel also set JWT_SECRET and NEXT_PUBLIC_SITE_URL.
• Read the platform build log — a missing variable or a Node version mismatch is named directly there.

App behaves as "unlicensed" unexpectedly after deploy

The license is bound to your domain. After moving domains, the previously activated record won't match the new host. Activate the new domain (Install Wizard or Admin → License); if you're retiring the old domain, deactivate it first to release the seat.

Triage order

A quick order that resolves most problems:

1. Read the host/platform logs — the error usually names the fix.
2. Confirm env values: DATABASE_URL, JWT_SECRET, and (on Vercel) NEXT_PUBLIC_SITE_URL.
3. Confirm in-app integration config: storage and SMTP credentials in the admin panel.
4. Verify connectivity: database reachable, storage bucket reachable and public.
5. Redeploy / restart, then hard-refresh the browser.

© CreativeCape Solutions · creative-cape.com · support@creative-cape.com