JustFlows

Documentation is English-only for now. The rest of the site follows your language.

Troubleshooting

Common install, cache, API, and plugin problems — and where to look first.

6 min read

I only see under construction.
Install sets site_public=false. Sign in as admin or editor, open Settings, and publish the site. Anonymous users (and the public API) get a 404-style empty site until then.
The public API returns 404.
Enable Public API in Settings. Confirm the site is public. Only published content is listed. Check locale matches a site language.
Admin mutations fail with CSRF errors.
Send cookie jf_csrf and header x-csrf-token on POST/PATCH/PUT/DELETE to /api/*. Login and install are exempt. The SPA does this automatically; your own scripts must copy the cookie.
I changed CACHE_* or gzip and nothing happened.
The cache singleton is created once per process. Restart Node, or save from Tools so Passenger writes tmp/restart.txt.
Pages look stale after I edited content.
Content routes invalidate content: on save. If you edited theme CSS or menus, wait for TTL or Clear cache now. Preview with ?preview bypasses page cache.
Plugin upload is rejected.
The package must declare its own license, and that license must be GPL-compatible (core is MIT; extensions are not). Id must be namespaced (acme.plugin). If JUSTFLOWS_REQUIRE_SIGNED_PACKAGES=1, the digest must be trusted or the archive signed. Check the zip is a valid .jfpkg.
Admin UI says it is not built.
The server serves apps/server/admin-ui/dist. Run the admin production build (or pnpm dev that builds it). Docker images include the built SPA.
Database connection fails in the wizard.
Driver, host, port, name, user, password must match. Docker Postgres is on the compose network — use the service hostname from the compose file, not localhost from inside the web container unless ports are mapped that way.
CLI talks to the wrong host.
Set ADMIN_URL to the same origin the browser uses. Default is http://localhost:3001.

Tip

Site Health (/admin/health) and LOG_LEVEL=debug are the first two diagnostics. GitHub issues: justflows/justflows.