Troubleshooting and FAQ

Start with:

npm install
npm run dev

npm install is safe to rerun. If something still looks wrong, npm run setup is also safe to rerun: it preserves an existing .env, reinstalls locked dependencies, applies migrations, and checks the bundled pose collection.

If npm start reports a missing production build, run npm run build:web.

The embedded database does not open

Confirm the project directory is writable and PGLITE_DATA_DIR points to a writable location. The default is storage/pglite. Only one PoseForge server process can open a PGlite data directory at a time; stop duplicate processes and retry. A stale storage/pglite/postmaster.pid left over from an unclean shutdown can also block startup; it is safe to remove once you've confirmed no PoseForge server process is actually running.

If the error is Aborted(). Build with -sASSERTIONS for more info. instead of a lock error, the embedded database's WAL is corrupted (usually from the process being killed mid-write). See PGLITE_RECOVERY.md for the recovery runbook. PoseForge also takes an automatic daily backup to backups/pglite/ (on every startup and once per day thereafter) to cap the worst-case data loss.

An optional PostgreSQL server does not connect

Set both DATABASE_MODE=postgres and a valid DATABASE_URL. Confirm the server is running and accepts connections from PoseForge. Remove those overrides to return to the embedded PGlite default.

Existing PostgreSQL data is missing after switching to PGlite

Stop PoseForge, keep the old PostgreSQL DATABASE_URL in .env, and run:

npm run db:import-postgres -- --yes

The importer validates every application table before cutover and retains the previous PGlite directory as a timestamped backup. Restart PoseForge afterward.

The app reports a missing table or migration

Run:

npm run migrate
node scripts/verify-setup.js

Migrations are incremental and safe to rerun.

A fresh clone has no poses

Confirm that storage/pose-library/seed/ contains the committed PNG files, then run:

npm run migrate
node scripts/verify-setup.js

The verification command checks both database records and their local files.

An engine is unavailable

Open Settings and read the readiness reason shown for that engine.

Codex CLI: install codex, then run codex login and complete the sign-in flow. Use CODEX_BIN if the executable has a custom path.
If either CLI was just installed or just added to PATH, open a new terminal (or run source ~/.zshrc / source ~/.bashrc, matching your shell) so the updated PATH takes effect, then restart the PoseForge server (npm run dev or npm start) so it picks up the newly available CLI.
ComfyUI: start ComfyUI, keep its API on a loopback address, and provide an API-format workflow containing the placeholders documented in Settings.
Cloud API engines: verify the API key, account access, quota, and selected model. Provider subscriptions and API billing are often separate products.

Generation finishes without an image

Read the server log for the engine’s exact failure reason.
Verify the selected model supports image creation and image references.
For ComfyUI, confirm the configured output node produces an image and all required models and custom nodes are installed.
Try one character and one pose before debugging a multi-person composition.
Do not post private input images or credentials in a public issue.

The browser shows an old landing-page image

Stop the development server, restart it, and hard-refresh the browser. If the asset filename was reused, clear the site cache. Contributors should prefer a new filename for replaced launch assets so deployed caches cannot retain an older image indefinitely.