Troubleshooting

Fix common issues with local startup, database paths, browser connections, and archive exports.

Check each process independently

Problem	What to check
Backend unavailable	Look at terminal A and run `curl --fail http://127.0.0.1:4318/api/health`. Confirm HOST and PORT match the guide.
Page unavailable	Look at terminal B. If port 3001 is occupied, stop the conflicting process or choose a different allowed frontend origin. The backend CORS list in this version accepts localhost/127.0.0.1 on ports 3000 and 3001.
Page loads but API or WebSocket fails	Make sure you are using `NEXT_PUBLIC_API_BASE_URL` and `NEXT_PUBLIC_WS_BASE_URL`, including the `_BASE_` part. Older README examples without it do not match the current source. Restart Next after changing its environment.
SQLite native binding fails	Confirm Node 22 and rerun the locked installation for that runtime. A native module built under another Node version may need rebuilding. Check the actual error message.

Distinguish empty, new and existing data

A new DB_PATH creates a different workspace. Seed configuration runs only for an empty room database—editing the seed file does not automatically replace existing rooms.

Use the same DB_PATH and ARCHIVE_DIR when restarting. Relative paths change meaning with the working directory, which is why Quick Start supplies absolute paths.

If an archive is listed but cannot be read, check whether its file still exists under the configured archive directory. Export errors can mean a missing archive path, invalid JSON, or an unwritable destination. The exporter writes template.json, not a complete database backup.

Dialogue does not advance

Check three things first: provider/model settings, the selected role, and any question waiting in ASK.

A successful local archive does not test credentials, provider availability, or model behavior. Avoid repeatedly starting automatic dialogue while diagnosing a failure. Inspect local logs without posting credentials or full private conversations.

Known snapshot limits

This is a development web app, not a verified desktop release or a hosted multi-user deployment. The browser title and product README use different names.

The template exporter omits display definitions, as detailed in Archives and templates. The documented first-use acceptance covers local variables, archives, and template output. Live model quality and OAuth are outside that evidence.