Troubleshooting

Something is not working. This page is organized by what you see, such as a warning in the address bar or an email that never comes, and for each one explains the usual causes and what to do about them, most likely first.

Two checks that answer most questions

1. Is Tesria running? Open https://your-server/api/health. If it answers with a line that includes "status":"ok", Tesria itself is fine and the problem is somewhere between it and you. If nothing answers, see The page will not load at all, below.

2. Are all its parts running? Tesria is several programs working together, each in its own container. On the server, run docker compose ps. Each should say running (or Up), and those with a health check healthy. One that says restarting or exited is where to look.

Opening Tesria

The address bar says “Not secure”, or the browser warns before opening Tesria

The browser does not trust the certificate your server showed it. The connection is still encrypted; the browser just cannot confirm who issued the certificate. The usual causes:

• This device has not been told to trust your server yet. A Tesria on your own network makes its own certificate, which no browser trusts until you say so, once on each device. Trusting the local certificate walks you through it in about three minutes.

• You opened Tesria by a number, such as 192.168.1.50. Certificates are issued for names, so a number keeps warning even on a device that trusts the server. Open it by its name instead, such as studio.local: see Opening Tesria by name.

• The browser still remembers the old answer. Quit it completely and open it again. Closing the window is not always enough: in Chrome or Edge, type chrome://restart or edge://restart into the address bar; in Safari, press ⌘ Q.

• Firefox keeps its own list. A device can trust your server and Firefox still not. Trusting the local certificate has the extra step, under Firefox.

• Every device started warning at once. The server made a new certificate authority, because the place it keeps certificates was deleted, for example by docker compose down -v or a move to a new machine without it. Every device needs to trust the server again. Ordinary restarts and upgrades never do this.

Tesria’s name takes a few tries to open

You type studio.local and the browser says it cannot find the server, then it works on the second or third try. That is how names ending in .local are found: the device calls out to the whole network, “who is studio?”, and waits for the answer. Wi-Fi sometimes drops those calls, Windows asks your router first and can give up before the answer arrives, and a sleeping server answers late.

None of it is Tesria, and all of it can be fixed: keep the server awake and, if you can, plugged in with a cable; check two router settings; or give the server a fixed address and a name your whole network knows. Opening Tesria by name explains each, from easiest to most thorough.

The page will not load at all

The browser says it cannot reach the site, or waits and gives up.

• Tesria is not running. Run docker compose ps on the server. If nothing is listed, or something has exited, start everything with docker compose up -d.

• It is still starting. The very first start builds Tesria and sets up its database, which takes a few minutes. After a restart, give it a minute.

• Something failed to start. Read the end of its log: docker compose logs app --tail 50 for Tesria itself, or the name of whichever part is not running. The last lines usually say why.

• The device is on another network. A phone on mobile data, or a laptop on a guest Wi-Fi, cannot reach a server on your home or office network. Guest networks usually keep their devices apart on purpose.

• The address is wrong. Check the name, and that it starts with https://.

The page is blank, or looks wrong after an upgrade

A tab that was open during an upgrade can hold on to parts of the old version. Close the tab and open Tesria again, or reload while holding Shift (in Chrome, Edge and Firefox). If it is still blank, check https://your-server/api/health to see whether Tesria is running.

Everything is read-only for a few minutes

An administrator is restoring a backup. While a restore runs, you can read the wiki but not change it, and /api/health shows "maintenance" with the reason. It ends by itself when the restore is done. See Restoring and undo.

Signing in

“Incorrect email or password”, with the right password

After 5 wrong passwords in a row, the account is locked for a minute, and each wrong try after that doubles the wait, up to 15 minutes. While it is locked, even the right password is refused with the same message, so that nobody can use the message to find out whether they guessed right. Wait, and try once, carefully.

An administrator can end it sooner: Unlock next to the account in Admin, Users (Admin is in the top bar; in a narrower window it is under More, and on a phone in the ☰ menu). If you have simply forgotten the password, see Resetting a password.

“Too many attempts. Wait a minute and try again.”

Too many sign-in attempts came from your address in the last minute: 10, by default, counting everyone who shares that address. Wait a minute. If many people sign in from one office connection, an administrator can raise the limit in Admin, Security (Admin is in the top bar; in a narrower window it is under More, and on a phone in the ☰ menu), under Brute-force protection.

You lost the phone with your authenticator app

• Use a recovery code. When Tesria asks for the six-digit code, enter one of the recovery codes you saved when you turned two-factor on. Each works once. Then set two-factor up again on your profile with your new phone. See Two-factor and recovery codes.

• No recovery codes? Ask an administrator to choose Turn off two-factor for your account in Admin, Users (Admin is in the top bar; in a narrower window it is under More, and on a phone in the ☰ menu). Sign in with your password, then set it up again. Only the owner can do this for an administrator, and nobody can do it for the owner, which is why the owner’s recovery codes matter most.

Signed out after a restore

Restoring a backup brings back the wiki as it was when the backup was taken, including who was signed in. Sessions started after that moment no longer exist. Sign in again.

Writing and editing

“Offline: your changes are local until reconnected”

The editor lost its connection to the part of Tesria that shares edits between people. Keep writing: your changes are kept in the browser and sent when the connection comes back. If it never does, ask whoever runs Tesria to check the collab container: docker compose ps collab and docker compose logs collab --tail 50.

“This page changed while you were editing, so it was not published”

Someone else, a script or an assistant updated the page after you started. Nothing is lost: their change is highlighted in your editor. Accept or reject it, then choose Update again. See Changes from assistants and the API.

There is no Edit button

You can read the page but not change it: the space, or this page, lets you view only. Ask one of the space’s administrators for edit access. See Who can see a space and Restrictions.

A file will not upload

Each attachment can be up to 25 MB. For a larger video or file, share a link to it instead, or embed it from a site such as YouTube.

An embed says the site is not allowed

Only sites on your Tesria’s allowed list can be shown inside a page. An administrator can add one in Admin, Settings (Admin is in the top bar; in a narrower window it is under More, and on a phone in the ☰ menu), under Embeds. Meanwhile the embed shows a link that opens it.

Email

Email never arrives

Password resets, invitations, alerts and notifications all need Tesria to be able to send email. Work down this list:

1. Is sending switched on? In Admin, Settings (Admin is in the top bar; in a narrower window it is under More, and on a phone in the ☰ menu), under Email, Send email must be ticked. When it is off, no email is even attempted.

2. Send a test. Choose Send test email to me. It says straight away either Sent: check your inbox, or Not sent with the mail server’s own reason, such as a wrong password.

3. Check the port and encryption together. Port 587 goes with STARTTLS, and port 465 with SSL on connect. A mismatch usually fails with a timeout.

4. Check the From address. Most mail services only send from an address or domain you have verified with them, and refuse or quietly drop anything else.

5. Look in the spam folder. Mail from a new sender often lands there at first. Marking it as not spam helps the next one.

See Email (SMTP) for every setting.

Notifications arrive in the app but not by email

Everyone starts with notification emails off; each person chooses on their own profile, under Email notifications: immediately or as a daily digest. See Email notifications.

Backups and exports

A backup shows “Last run failed”, “Overdue” or “Agent offline”

Admin, Backups (Admin is in the top bar; in a narrower window it is under More, and on a phone in the ☰ menu) shows a card for each of Tesria’s two backup services, with a colored dot and a word for how it is doing:

• Last run failed: the last backup did not complete. The card shows the error. Tesria tries again after 15 minutes, then waits twice as long after each further failure, up to 6 hours.

• Overdue: no backup has succeeded for longer than the schedule allows.

• Agent offline or Not reporting yet: the backup service is not checking in. It may have stopped, or, on a new install, not have started yet.

• Disk nearly full: the backups are running out of room. Free some space, or keep fewer backups (see Retention).

On the server, check the two services and read the end of their logs:

docker compose ps backup pgbackrest
docker compose logs backup --tail 50
docker compose logs pgbackrest --tail 50

A service that is not running comes back with docker compose up -d. The log’s last lines that start with ERROR say what failed. See Backups and recovery for how the two services work.

The cloud copy fails with a “not found” or name error

Cloud storage services address a bucket in one of two ways, and Tesria has to use the one yours expects. Set OFFSITE_CLOUD_URI_STYLE in the .env file to path (for MinIO and most storage you run yourself) or host (for Backblaze and AWS), run docker compose up -d, and choose Test connection again. See Offsite copies.

A network drive backup seems stuck, on a Mac

Docker Desktop is waiting for your permission to use the folder on the network drive, and waits rather than failing. Allow it when macOS asks, or add the folder in Docker Desktop’s settings, under file sharing. See Offsite copies.

PDF or HTML export says there is no export renderer

The message This instance has no export renderer configured means the service that turns pages into PDF and HTML files is not set up on this server. It runs only when PDF_SHARED_SECRET is set in the .env file. Meanwhile, Markdown exports work. See Configuration reference.

An export option is missing

Either your role may not export (an administrator can change that in Admin, Roles (Admin is in the top bar; in a narrower window it is under More, and on a phone in the ☰ menu)), or this space has turned that kind of export off. See Turning exports off.

Still stuck?

Look through the FAQ, and Health checks and monitoring for how to see what Tesria is doing. When you ask someone for help, include what you did, what you expected, what happened instead (the exact words of any message), and the version, from Administration, About (or https://your-server/api/health while signed in).