A free, open-source, self-hosted place to write a novel.
Fablewright docs troubleshooting.md
17 kB · 345 lines
Markdown
at main

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/health is 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_URL is 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.js refuses to start and prints both versions. Restore the database from before the upgrade, or start the build that wrote it. FABLEWRIGHT_ALLOW_NEWER_SCHEMA=1 starts anyway, but use it only when the release notes say that every migration only adds a column.
  • drizzle/ is missing. A bare Node install needs drizzle/ beside server.js. The app applies the migrations on boot.
  • An invalid environment value. The process prints the variable and the reason, then exits. SMTP_PORT must 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.

  1. Make sure that the entry point is node server.js, not node build. server.js exists to set the origin for a plain HTTP install.
  2. If ORIGIN is set, make sure that it matches the address in the browser, including http or https and the port.
  3. If a proxy terminates TLS and ORIGIN is empty, set TRUST_PROXY=1 and make sure that the proxy overwrites X-Forwarded-Proto. The app trusts the last value in that header.
  4. Make sure that the proxy does not forward a second, conflicting X-Forwarded-Proto from the client.
  5. For a direct install, leave ORIGIN empty and TRUST_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_SECRET invents 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.db
    

    On Docker Compose, use docker compose exec while the app runs:

    docker compose exec fablewright node scripts/ops.mjs reset-password \
      --email admin@example.com --generate
    
  1. Make sure that SMTP_HOST and MAIL_FROM are both set.
  2. Make sure that ORIGIN or INSTANCE_ORIGIN is set. Without a declared address, the app writes the link to the log instead of mailing it.
  3. Read the log. A send failure writes the link to the log and names the error.
  4. Check the spam folder and the relay's own log.
  5. 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 ORIGIN and no INSTANCE_ORIGIN, passkeys work on localhost only. Other addresses hide the controls. This includes 127.0.0.1 without a declared origin. Set ORIGIN, or INSTANCE_ORIGIN for 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 #

  1. Download the unsaved words from the footer before changing anything else.
  2. Check /api/health. If it fails, the app or the database is down.
  3. Check the disk. A full disk stops writes. df -h and du -sh on the data directory show the space.
  4. Check the log for SQLITE_BUSY or database 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.
  5. Leave the tab open while the save retries. Do not create another competing editor for the same scene.
  6. 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=101M leaves 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 .txt files.
  • 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 .zip export 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-only backup 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.lastVersion in manifest.json.
  • The restore path is wrong. Pass the database path the instance will use with --database, or set DATABASE_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.

  1. Preserve unsaved browser words. Stop avoidable writes while you recover space.

  2. If the disk cannot hold a backup, use backup --out /mounted/other-disk/backups on another writable disk.

  3. If backup cannot run, preserve existing backups before removing files. Do not delete live database journals.

  4. Remove unneeded old backups only after preserving an off-machine copy. The tool keeps eight by default, and --keep N changes that.

  5. Remove unreferenced upload files:

    node scripts/ops.mjs prune-uploads
    node scripts/ops.mjs prune-uploads --apply
    
  6. Drop preserved originals if the display copies are enough:

    node scripts/ops.mjs prune-uploads --originals --apply
    
  7. Expire old recovery history. A dry run reports eligible versions:

    node scripts/ops.mjs prune-history
    node scripts/ops.mjs prune-history --apply
    
  8. 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 --apply removes 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 --apply keeps 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.

  1. Read the log.
  2. Make sure that the process is running and the port is correct.
  3. Make sure that the database path exists and is writable.
  4. Make sure that drizzle/ sits beside server.js.
  5. 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.