Troubleshooting

Setup & First Run

I can’t find the setup wizard

Navigate directly to /baan-admin/setup:

http://localhost:3000/baan-admin/setup

The wizard is only accessible when no admin account has been created yet. If setup was already completed, the wizard redirects to the login page.

---

I forgot my secret admin URL

The admin URL contains a random path segment (e.g. /baan-admin/xK9mP2qR.../). If you lose it:

Self-hosted:

Query the database directly:

sqlite3 data/app.db "SELECT json_extract(value, '\$.adminUrlPath') FROM settings WHERE key = 'security';"

Vercel (Turso):

The admin URL is stored in your Turso database, not in Vercel env vars. Query it from the Turso shell:

turso db shell your-db-name "SELECT json_extract(value, '\$.adminUrlPath') FROM settings WHERE key = 'security';"

---

I’m locked out due to IP restriction

If you enabled IP restriction with the wrong IP and can no longer access the admin panel:

1. Stop the server (Ctrl+C) — the database may be locked while the server is running
2. Run the following SQL against your database:

UPDATE settings
SET value = json_set(value, '$.ipRestrictionEnabled', json('false'), '$.allowedIPs', json('[]'))
WHERE key = 'security';

Local SQLite:

sqlite3 data/app.db

Then paste the SQL above.

Turso:

Use turso db shell <db-name> or the Turso dashboard SQL editor.

3. Restart the server if you stopped it in step 1 — the settings take effect within seconds once the server is running

---

I forgot my admin password

Self-hosted:

Reset via the CLI:

npm run reset-password

Or delete the user from the database and re-run setup:

3000/baan-admin/setup

sqlite3 data/app.db "DELETE FROM users;"

Vercel (Turso):

Delete the user from the Turso database and re-run setup:

turso db shell your-db-name "DELETE FROM users;"
# Then visit https://your-app.vercel.app/baan-admin/setup

---

The setup wizard shows “Setup already completed”

An admin account already exists in the database. If this is unexpected (e.g. after a fresh clone), check that data/app.db is empty or doesn’t contain user records:

sqlite3 data/app.db "SELECT COUNT(*) FROM users;"

If the count is non-zero and you want to restart: DELETE FROM users; and revisit the wizard.

---

Themes

My new theme isn’t showing in the Customizer

The theme manifest is generated at build time. After adding or removing a theme folder, you must restart the dev server:

# Stop the running server (Ctrl+C), then:
npm run dev

For production, run a full rebuild:

npm run build

The generate-theme-manifest prebuild script scans themes/*/theme.json and registers all valid themes. A theme won’t appear if:

• The folder name or theme.json has a typo
• theme.json is missing required fields (name, displayName)
• The dev server hasn’t been restarted since the folder was created

---

AI theme generation stops without an error (Vercel)

Theme generation makes two sequential AI calls. Vercel’s serverless functions have a plan-based execution limit:

Plan	Max duration
Hobby	60 seconds
Pro	300 seconds

If generation silently stops mid-way, the function timed out before a response was returned.

Fix: Use a fast model such as GPT-4.1 Mini, Gemini 2.5 Flash, or Claude Haiku 4.5. These typically complete both AI calls within 30 seconds on Hobby. Slower models (GPT-5, Claude Sonnet, Gemini Pro) may exceed the 60-second limit.

If you consistently need more time, upgrade to Vercel Pro where the limit is 300 seconds.

---

The site shows a blank page after switching themes

A broken theme component is throwing an error. Check the terminal running npm run dev for a stack trace. Common causes:

• A TSX component references a prop that doesn’t exist in the current context
• config.ts has a syntax error
• A required export is missing from a component file

Fix the error in the theme file — the dev server hot-reloads component changes. If the error persists after fixing, restart the dev server.

To recover quickly, switch back to the default theme via the database:

sqlite3 data/app.db "UPDATE settings SET value = '\"default\"' WHERE key = 'theme';"

---

Theme CSS changes aren’t applying

CSS changes in styles/theme.css should hot-reload in the dev server. If they’re not:

1. Check that you’re editing the correct theme’s styles/theme.css (not a built-in theme’s file)
2. Hard-refresh the browser (Cmd+Shift+R / Ctrl+Shift+R) to clear cached styles
3. Verify the CSS variable names match what the component uses

---

Build & Compilation

npm run build fails with a TypeScript error

Build errors in theme components are the most common cause. The error message will point to the file and line:

Type error: Property 'xxx' does not exist on type 'PostCardProps'

Check the AI Agent Built Themes Guide for the full prop type definitions.

If the error is in a non-theme file, check git for recent changes and revert if needed.

---

npm run build fails with “Cannot find module”

Run npm install to ensure all dependencies are present:

rm -rf node_modules
npm install
npm run build

---

Full clean reset

To return the project to a completely fresh state (removes the database, build cache, and all dependencies):

rm -rf .next .next-output node_modules data .test-output
npm install

Path	Contents
.next	Build cache
.next-test	Test build cache
node_modules	Dependencies
data	SQLite database (settings, users, sessions)
.test-output	Generated E2E test files

After running this, start the server with npm run dev and complete the setup wizard at /baan-admin/setup.

---

Storage

Files aren’t uploading (GCS / S3 / R2)

1. Check environment variables — ensure all required variables for your provider are set (see Environment Variables)
2. Check credentials — test the credentials independently (e.g. with aws s3 ls for S3)
3. Check bucket permissions — the service account or IAM user must have read and write access
4. Check the admin error log — go to Admin → Settings → System to see recent storage errors

For GCS specifically: the GOOGLE_CLOUD_CREDENTIALS_BASE64 value must be a single-line base64 string with no newlines. Regenerate it with:

base64 -i service-account.json | tr -d '\n'

---

Local filesystem works but cloud storage doesn’t after switching providers

After switching the storage provider in Admin → Settings → System, existing content is still in the old location. Use the migration tool:

1. Go to Admin → Settings → System
2. Select your new provider and enter credentials
3. Click Migrate — Baan copies all files to the new provider
4. Save — the new provider becomes active

---

Database

Turso connection error (libsql://...)

Error: Failed to connect to database

1. Check DATABASE_URL format: libsql://your-db-name.turso.io (not https://)
2. Check DATABASE_AUTH_TOKEN is current — Turso tokens can expire; regenerate with turso db tokens create your-db-name
3. Check the database exists: turso db list

---

”Database is locked” error (SQLite)

This happens when two processes try to write to data/app.db simultaneously. Causes:

• Two npm run dev processes running at the same time — kill all and restart one
• A test run left a lock — check for zombie processes: lsof | grep app.db

---

Network & Port

EADDRINUSE: address already in use :::3000

Port 3000 is already in use. Find and kill the process:

lsof -i :3000
kill -9 <PID>

Or run on a different port:

PORT=3001 npm run dev

---

ERR_NAME_NOT_RESOLVED on localhost (macOS)

Some macOS systems have issues resolving localhost via IPv6. The project ships with a DNS patch script that forces localhost → 127.0.0.1. This patch is applied automatically by npm run dev. If you’re running the server another way, use:

node --import ./scripts/patch-dns.mjs ./node_modules/.bin/next dev

---

AI Features

AI assistant returns “API key not configured”

API keys can be set in two places:

1. Admin panel (self-hosted): Admin → Settings → AI → API Keys
2. Environment variables (Vercel / any environment): ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY

Make sure the provider you selected in Settings → AI → Default Provider has a corresponding API key.

---

Knowledge Graph extraction fails or returns empty results

1. The article must have a saved body (draft or published) before extraction
2. Check that your AI provider is configured and the API key is valid
3. Very short articles (< 200 words) may not contain extractable entities — this is expected behavior
4. Check token usage in Admin → Settings → AI — if you’ve hit your provider’s rate limit, wait and retry

---

Vercel-Specific

Admin panel is inaccessible after deploy

If you can’t reach /baan-admin/[path]/login after deploying:

1. Confirm DATABASE_URL and DATABASE_AUTH_TOKEN are set in Vercel env vars and point to the same Turso DB the setup wizard wrote to
2. Confirm the setup wizard completed — query Turso for the admin path: turso db shell <name> "SELECT json_extract(value, '$.adminUrlPath') FROM settings WHERE key = 'security';"
3. If Turso returns no row, the wizard never ran on this deployment — visit /baan-admin/setup to complete it

ISR pages aren’t updating after publishing

Vercel’s ISR cache can take up to the revalidation interval to update. To force an immediate update, trigger a revalidation from the admin panel (publish or update the post again), or purge the cache in the Vercel dashboard.