Troubleshoot a Fablewright instance #
If the editor holds unsaved words, download or copy them before troubleshooting. Keep that tab open. Do not clear site data, reload, or sign out before you have another copy.
For an operator, start with the version, commit, and log. Writers without server access can report the browser message and ask the admin to collect the logs.
- The admin page shows the version, the commit, the database path, the migration level and the newest restore drill.
/api/healthis public and answers with the version and the commit.- Docker Compose:
docker compose logs -f fablewright - systemd:
journalctl -u fablewright -f - Cloudron:
cloudron logs -f
Look for the [fablewright] ... listening on ... line. Container setup and
migration output can precede it. Use the admin page or /api/health for the
embedded build identity. See installation for setup and
operations for backup and restore procedures.
Dependency installation fails #
If pnpm reports ERR_PNPM_NO_AGENT_SKILLS_DIR, create .agents/skills in the
checkout before installing. The dependency permissions require it:
mkdir -p .agents/skills
pnpm install --frozen-lockfile
Use Node 24 or newer and pnpm 12.21.0. Install development dependencies before building. A clean runtime-only dependency install does not supply the build tools. Do not work around an install failure by removing the lockfile or updating the pinned Drizzle packages.
The app does not start #
Read the last lines of the log first. The usual causes are:
- The port is in use. Another process holds
PORT(3000 by default). Stop it, or set another port. - The data directory is not writable. The container writes to
/data, the systemd unit to/var/lib/fablewright, and Cloudron to/app/data. Make sure that the user that runs the app can write there. The Docker image runs as UID and GID 1001. A bind mount must permit that user to write. A database file also needs a writable parent for its journal files. - The database path is wrong. A relative
DATABASE_URLis resolved from the working directory. Use an absolute path in a service or container. - A migration failed. The process exits and the database stays at its old shape. The log names the migration. Restore the backup taken before the upgrade if the cause is not obvious.
- The build is older than the database.
server.jsrefuses to start and prints both versions. Restore the database from before the upgrade, or start the build that wrote it.FABLEWRIGHT_ALLOW_NEWER_SCHEMA=1starts anyway, but use it only when the release notes say that every migration only adds a column. drizzle/is missing. A bare Node install needsdrizzle/besideserver.js. The app applies the migrations on boot.- An invalid environment value. The process prints the variable and the reason,
then exits.
SMTP_PORTmust be a whole number between 1 and 65535, for example.
Every form submission is rejected #
The browser shows Cross-site POST form submissions are forbidden.
SvelteKit compares the browser's Origin with the app's own origin on a form
POST. The app has to know its public scheme and host.
- Make sure that the entry point is
node server.js, notnode build.server.jsexists to set the origin for a plain HTTP install. - If
ORIGINis set, make sure that it matches the address in the browser, includinghttporhttpsand the port. - If a proxy terminates TLS and
ORIGINis empty, setTRUST_PROXY=1and make sure that the proxy overwritesX-Forwarded-Proto. The app trusts the last value in that header. - Make sure that the proxy does not forward a second, conflicting
X-Forwarded-Protofrom the client. - For a direct install, leave
ORIGINempty andTRUST_PROXY=0.
A wrong ORIGIN can also break authentication and send reset links to the wrong
address. Use a bare origin, such as https://fable.example.com, without a path.
Restart after changing it. A Compose .env copied from the development example
points at port 5173, not the production port 3000.
Sign-in fails #
-
The password is wrong. The form says so. Use the reset link, or ask the admin to set a password on Instance → Accounts.
-
The account is disabled. The form says that the account is disabled. The admin enables it on Instance → Accounts.
-
Too many attempts. The sign-in throttle allows five failures per email in five minutes, and fifty per address in fifteen minutes. Wait for the window. The counts live in the process, so restarts clear them, but repeated restarts remove the protection rather than fix a wrong password or proxy configuration.
-
Existing sessions end after a restart. A bare Node install with no
BETTER_AUTH_SECRETinvents a new secret at each start. Sessions end, and passwords still work. Set a persistent secret in the service. -
The admin is locked out. The admin console needs a session, so use the command line:
sudo -u fablewright node /opt/fablewright/scripts/ops.mjs reset-password \ --email admin@example.com --generate \ --database /var/lib/fablewright/fablewright.dbOn Docker Compose, use
docker compose execwhile the app runs:docker compose exec fablewright node scripts/ops.mjs reset-password \ --email admin@example.com --generate
A password reset link never arrives #
- Make sure that
SMTP_HOSTandMAIL_FROMare both set. - Make sure that
ORIGINorINSTANCE_ORIGINis set. Without a declared address, the app writes the link to the log instead of mailing it. - Read the log. A send failure writes the link to the log and names the error.
- Check the spam folder and the relay's own log.
- Set the password from Instance → Accounts if the writer cannot wait. The admin sees the new password once and can pass it on.
A relay that stops answering cannot block the form. The send has a ten-second connect timeout, and a failure falls back to the log.
Compose does not automatically pass SMTP values from .env to the container.
Use the mail override, then recreate the
container. For systemd, put values in the service environment and restart it.
A logged reset link is a full URL when a declared address exists. Otherwise it is a path. Prepend the correct instance address before sending it. Do not paste either form into a public bug report.
Passkeys are not offered #
- The browser needs HTTPS or localhost. A plain HTTP address on a LAN cannot create a passkey.
- The address is not declared. With no
ORIGINand noINSTANCE_ORIGIN, passkeys work onlocalhostonly. Other addresses hide the controls. This includes127.0.0.1without a declared origin. SetORIGIN, orINSTANCE_ORIGINfor several domains. - The writer is on an alias domain. A passkey is bound to one domain. Use the primary address, or keep the password for the alias.
- The session is more than a day old. Adding a passkey asks for a session made in the last day. Sign out and back in.
- The instance moved to a new domain. Remove the old passkey at the new address and add a replacement.
A save does not land #
- Download the unsaved words from the footer before changing anything else.
- Check
/api/health. If it fails, the app or the database is down. - Check the disk. A full disk stops writes.
df -handdu -shon the data directory show the space. - Check the log for
SQLITE_BUSYordatabase is locked. The app waits five seconds for a write lock. A second process that holds the database, or a restore while the app runs, is the usual cause. - Leave the tab open while the save retries. Do not create another competing editor for the same scene.
- If the instance is reachable again, press the save control or
Ctrl+S.
The browser buffer can recover pending words when local storage works. It is not a guarantee against browser or device failure, and it is not a project backup. Use the same browser profile and instance address to look for a recovery prompt.
If the failure says that you are signed out, preserve the words before signing in again. If it says the item is gone, ask the owner about deletion or revoked access. A lost response can also mean the server accepted a save that the browser could not confirm. Read any conflict prompt before replacing the server copy.
Two editors disagree #
A conflict means the server has a newer revision than the one your editor loaded. It can come from another tab, another writer, a restore, or a save whose response was lost.
Download mine keeps your text without resolving the conflict. Keep my version replaces the saved copy. Use saved version adopts it. Download first if you need both, then combine the text manually. There is no automatic merge.
A panel covers the prose on a phone #
Use the panel's close control to return to writing. The manuscript tree becomes a drawer, and workspace actions move into the header's Actions menu. Closing a planning panel waits for its save. A refused save can intentionally keep it open.
Preserve the planning text before reloading. Use the row actions or Move to for manuscript moves on touch screens instead of dragging.
An import is refused #
- The file or request is too large. The file limit is 100 MiB, shown as 100 MB.
The default
BODY_SIZE_LIMIT=101Mleaves room for multipart headers. A proxy can impose its own lower limit, so allow more than 100 MiB there too. A route that is not an import has a much smaller limit, so a 413 on a save or a form means the body was too large for that route rather than for an import. - The file type is not supported. Import reads Fablewright archives, Scrivener
folders or ZIPs, standalone manuscript
.json,.docx,.md,.markdown, and.txtfiles. - The instance says it is busy. One import or export runs at a time, because
each one holds the server while it works. Four requests may wait their turn; the
next is refused with a message and
Retry-After. Try again in a moment, and do not start a second import while the first is still running. - The zip is damaged or has no
manuscript.json. Export the project again. - The archive is a newer format. The app refuses it by name. Import it on an instance that runs the same or a newer release.
- A standalone JSON has no images. That is expected. Import the
.zipexport when the notes have pictures. - The preview fails. The preview reads the file before the import. A damaged Word file or an unreadable Markdown file stops there, and the project is not created.
An uncertain response after submission is different from a failed preview. Refresh the library before importing again. The first attempt can already have created a project. Read the import and export guide for headings, conversion losses, pictures, and missing report downloads.
A restore is refused #
- The backup fails
verify. Do not restore it. The tool could not establish that the backup is usable. Use an older copy that passes verification. - The app is still running. Stop it first. A running app keeps writing to the database that the restore moves aside.
- A drill reports no uploads. A
--database-onlybackup or Cloudron snapshot does not carry images. Use a full backup for a standalone restore. Restore can leave destination uploads alone when a backup holds none. It cannot recreate the missing files. Cloudron's platform archive supplies them separately. - The database is newer than the build. Start the version that wrote the
backup. The backup records it as
schema.lastVersioninmanifest.json. - The restore path is wrong. Pass the database path the instance will use with
--database, or setDATABASE_URL.
On Cloudron, use the platform restore button. It restores the platform archive and
runs the restore hook before the app starts. Do not run restore by hand against
/app/data.
The disk is full #
The database, its WAL journal, the uploads directory, the backup directory and the
Cloudron snapshot all take space. Run these commands with the app's
DATABASE_URL, or pass --database.
-
Preserve unsaved browser words. Stop avoidable writes while you recover space.
-
If the disk cannot hold a backup, use
backup --out /mounted/other-disk/backupson another writable disk. -
If backup cannot run, preserve existing backups before removing files. Do not delete live database journals.
-
Remove unneeded old backups only after preserving an off-machine copy. The tool keeps eight by default, and
--keep Nchanges that. -
Remove unreferenced upload files:
node scripts/ops.mjs prune-uploads node scripts/ops.mjs prune-uploads --apply -
Drop preserved originals if the display copies are enough:
node scripts/ops.mjs prune-uploads --originals --apply -
Expire old recovery history. A dry run reports eligible versions:
node scripts/ops.mjs prune-history node scripts/ops.mjs prune-history --apply -
Only after enough space is available, compact the database:
node scripts/ops.mjs prune-history --apply --vacuum
--vacuum reads and writes the whole database, so run it while the instance is
quiet. Allow at least the database size in free space, with headroom for SQLite's
temporary files. Do not use --all unless
the disk is the emergency: it removes the versions that writers named.
Search finds nothing #
Search reads the server's copy, not the words in an unsaved tab. Save the scene first.
The index is built at boot when it is empty. Restart once after an upgrade from a build that did not have search. If results are still missing, check the log for a failed index build.
Images are missing #
- The backup held no uploads. A database-only backup and a Cloudron snapshot hold no images. A restore drill reports the missing files.
- The file was pruned.
prune-uploads --applyremoves files that no row names. A project deleted forever cannot be restored, so its images cannot come back. Export the project before you delete it for good. - The original was dropped.
prune-uploads --originals --applykeeps the display WebP and removes the full-size file. The note still shows the display copy. - The image is on a trashed note. Project archives keep images for notes in the trash. A standalone JSON does not carry images at all.
A word count looks wrong #
- A parent row sums its children. A book counts its chapters, and a chapter counts its scenes.
- A day counts words added in the scene editor, under the writer's local date. Deleting words never subtracts. Notes, imports, co-author words and guest edits do not count toward that writer's goal. The count uses positive differences between saved word counts, not every word typed. Equal-length replacement prose adds no words to that total.
- A project version or an export can contain work saved before the last autosave. Wait for the save before you take one.
Too many attempts #
The sign-in, sign-up, forgot-password, and reset-password forms are throttled.
Wait for the window.
A restart clears the counts, because they live in the process. If every writer
shares one bucket, the proxy is not passing the client address. Set
TRUST_PROXY=1 only when every request arrives through that proxy, and make sure
that it overwrites X-Forwarded-For.
The health check fails #
/api/health reads one row. A failure means the app did not start, the database
did not open, or a migration did not finish.
- Read the log.
- Make sure that the process is running and the port is correct.
- Make sure that the database path exists and is writable.
- Make sure that
drizzle/sits besideserver.js. - If the build is older than the database, start the build that wrote it.
Reporting a bug #
Include the version and commit from the admin page or /api/health. Name the
deployment, browser, steps to reproduce, and relevant log lines. Do not include a manuscript, a
password, a secret link, or the signing secret.
Open a report at https://tangled.org/katsuricata.com/Fablewright. Reproduce with the example project or made-up prose when possible. Include a screenshot for a layout failure after removing private text and addresses. CONTRIBUTING.md lists the details that help a maintainer reproduce it.
Report a security problem privately. The security policy says how.