Troubleshooting

An app has no icon, or a hostname instead of a name

monoki could not read the page. Common causes, in rough order of likelihood:

The app requires a login. Most self-hosted apps redirect an anonymous request to a sign-in page, which has its own (often generic) title and icon. Nothing to fix — set the name and icon by hand from the tile's Edit dialog.

The app is on a private address and private fetching is off. The add form says private_address_blocked when this happens. See MONOKI_ALLOW_PRIVATE_FETCH in Configuration.

monoki runs in a container and cannot reach your LAN. The container's network is not your host's. Run with --network host, or put the container on a network that can route to the app.

The app has no favicon, or offers only a mask-icon (which monoki ignores deliberately — it renders as a black blob). You get a letter tile. Upload an icon from Edit if you want one.

The site blocks unknown user agents. Some do. Nothing monoki can reasonably do about it.

Run with LOG_LEVEL=debug to see exactly which candidate was rejected and why:

level=DEBUG msg="sitemeta: icon candidate rejected" url=https://... err="..."

The name is right but ugly

stackoverflow.com instead of Stack Overflow means the page could not be read at all and monoki fell back to the hostname. A long title like Grafana — Kubernetes / Compute Resources means it was read but had no og:site_name. Either way, edit it — your name is never overwritten by a later re-read.

An icon is invisible

A logo drawn in one colour on a transparent background disappears against a plate of the same colour. Open Edit and set the plate to Light (for dark logos) or Dark (for light ones). See Icons & titles.

"That group is no longer shared with you"

Its owner revoked your access or deleted the group. The board polls every 15 seconds, so this appears shortly after.

A shared group does not appear

• Grants take effect on the next poll — up to 15 seconds.
• Check the owner shared it with the right account (Share lists who).
• A disabled account keeps its grants but cannot sign in at all.

Reordering snaps back

The board applies a move immediately and saves it in the background. If the save fails it reverts and shows "Couldn't save the new order." Usually the server is unreachable — check /healthz and the server log.

Reordering a group shared with you as a viewer is refused; you would see "This group is read-only."

"This is the last enabled admin"

monoki refuses any change leaving zero enabled admins. Promote somebody else first, or use the escape hatch:

monoki create-admin --username someone-else

Locked out entirely

systemctl stop monoki
monoki create-admin --username rescue --state-dir /var/lib/monoki
systemctl start monoki

This works directly against the database and ignores the API's guards.

"too many failed login attempts"

Ten failures from one address in a minute locks that address out for five minutes, and the lockout holds even for the correct password. Wait it out.

If everyone is locked out at once, your reverse proxy is probably not sending X-Forwarded-For, so every request looks like it comes from the proxy — see Running behind a proxy.

Sessions do not stick

The cookie is issued with Secure when the request arrives over TLS. If your proxy terminates TLS but does not send X-Forwarded-Proto: https, monoki issues a non-Secure cookie which some browser configurations will drop on an HTTPS page. Set the header.

"database is locked"

monoki serialises its own writes, so this points at another process holding the file — a second monoki on the same state directory, or an open sqlite3 session. Check with fuser /var/lib/monoki/monoki.db.

The UI is stale after an upgrade

The web UI is compiled into the binary. If you rebuilt from source, remember that go build does not run npm:

cd web && npm run build   # writes internal/webui/dist
cd .. && make build

Getting more detail

LOG_LEVEL=debug monoki run

Logs go to stderr as structured key/value pairs. Every failed request also logs the underlying error server-side, while the client only ever sees internal error — so the server log is the place to look.