Troubleshooting

Resolve local startup, database, browser connection and archive-export failures.

Check each process independently

Backend unavailable: check terminal A and curl --fail http://127.0.0.1:4318/api/health. Confirm HOST and PORT match the guide.
Page unavailable: check terminal B. If port 3001 is occupied, stop your own conflicting process or choose an allowed frontend origin deliberately; 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: use NEXT_PUBLIC_API_BASE_URL and NEXT_PUBLIC_WS_BASE_URL, including _BASE_. Older README examples without that part 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 installed under another Node version may need rebuilding; inspect the actual error.

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 can change meaning with the working directory, which is why Quick start supplies absolute paths.

If an archive is listed but cannot be read, check that 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 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 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.