Solutions for common installation, configuration, and operational issues.

---

🚀 Setup & Installation

“Initializing System” hangs

Symptoms: Splash screen stays on “Initializing System” indefinitely, or MIME type error (text/html instead of JavaScript).

Fix:

1. Delete config/private.ts if corrupted or empty, then restart bun run dev
2. Clear Vite cache:

   rm -rf node_modules/.vite
   bun run dev

3. Verify hooks.server.ts isn’t crashing before handleSystemState

---

Database connection failed

Symptoms: Check your credentials or ECONNREFUSED.

Fix:

Database	Action
MongoDB	Verify cluster hostname, whitelist your IP in Atlas
PostgreSQL / MariaDB	Database must exist before running wizard
SQLite	Ensure the directory for .db file has write permissions

Mechanics: src/databases/db.ts probes the connection. Use bun run check for isolated testing (MongoDB-specific diagnostics script not currently available).

---

Windows bun install corruption

Symptoms: bun install v1.3.11+ on Windows may write null bytes into package.json files or leave directories empty. Results in ParserError for @sveltejs/kit or esbuild.

Fix: Use npm install instead.

npm install    # Works reliably on Windows
bun run dev    # Bun's runtime works fine after npm install

This only affects the Bun installer on Windows. Bun’s runtime and bun run commands work normally.

---

🔐 Authentication & Sessions

“Unauthorized” or session expired immediately

Symptoms: Logged out immediately after login, 401 on all API calls.

Fix:

1. Clear browser cookies for your domain and retry
2. If you manually edited config/private.ts and changed JWT_SECRET_KEY, all sessions are invalidated — log in again
3. Ensure server system time is synchronized — divergent times cause JWT expiration

Account locked (HTTP 423)

Symptoms: Account locked after multiple failed login attempts.

Fix: Wait 15 minutes for automatic unlock. This is a security feature — 5 failed attempts trigger a temporary lockout.

---

🧩 Widgets & Collections

New widget doesn’t appear in Dashboard

Fix: Use the “Sync Widgets” button in ⚙️ Config → System Settings → Widgets. The scanner runs on HMR, but the database registry needs a manual trigger for new custom widgets.

Collection Builder field not saving

Fix: Ensure db_fieldName values are unique within a collection — duplicate names are rejected. Check the browser console for validation errors.

---

📈 Performance

“JavaScript heap out of memory”

Symptoms: Build fails on large media libraries or complex collections.

Fix: Increase Node.js memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"
bun run build

Slow API responses in production

Fix:

1. Verify Redis is configured and running (check config/private.ts)
2. Check MEDIA_STORAGE_TYPE — local storage is faster than cloud for small deployments
3. Run benchmarks to identify bottlenecks:

   bun test tests/benchmarks/database-performance.test.ts

---

🆘 Still Stuck?

1. View logs: Check the terminal where bun run dev runs
2. Run diagnostics:

   bun run check
   bun run test:unit

3. Community: GitHub Discussions · Discord

---

Related

• Security Overview
• State Management Architecture
• Database Architecture
• Login Resilience & Recovery