Start from the symptom you have

Two commands answer most of it

klyrn doctor                      # the whole server: 22 checks, failures first
klyrn site diagnose example.com   # one site: every probe, in the order a request travels

klyrn doctor reads the filesystem, systemd and the network directly, so it still answers when the panel is down. klyrn site diagnose runs every probe even after one has already failed, because a site can be broken in two ways at once, and sorts the findings with the critical ones first. Both name a cause rather than a symptom, and both print the evidence they used.

A diagnosis offers a repair by name when it has one. There are six, and no seventh; a repair has no field that could carry a command or a path. Run one like this:

klyrn site diagnose example.com --repair php.pool.restart

Every repair re-runs the diagnosis afterwards and reports the worst remaining finding, so you are told whether it worked rather than left to check.

The doctor exits 2 when something is failing and 0 when nothing is, so monitoring can use the exit code instead of parsing the output. Add --strict to exit 1 on a warning too, --verbose for the evidence behind every check rather than only the failing ones, and --json for a machine-readable report.

The site does not load at all

klyrn site diagnose example.com

Read the first finding. In practice it is one of four things, and the diagnosis distinguishes them:

• The site is suspended. The finding says so, and who suspended it. klyrn site unsuspend example.com.
• nginx is down, or this site has no vhost. The repair is nginx.reload, which starts nginx first if it is not running: a configuration cannot be reloaded into a service that is not there.
• nginx will not accept its configuration. The finding carries what nginx -t said. KLYRN validates before it swaps, so this usually means something outside KLYRN edited a file.
• The name does not reach this server. Nothing is wrong with the site. See the domain points somewhere else.

If the browser cannot reach the server at all, the problem is below KLYRN: check the provider's firewall and that ports 80 and 443 are open. klyrn doctor reports which process holds each port.

502 Bad Gateway

klyrn site diagnose example.com

nginx reached something and got nothing usable back, which for a PHP site means the FPM pool and for a Node site means the application. The diagnosis tells you which of four states it is in (the pool is not running, the pool file is missing, the socket is stale, or the app is down) and offers the matching repair.

The HTTP probe stays quiet when one of those has already explained the 502: it confirms the symptom, it does not also claim to be surprised by it.

If it started right after you changed a PHP setting, you may be on a build older than 0.3.0‑beta.4, which had a defect that left the pool serving through a socket nothing could reach. klyrn update, then klyrn site diagnose example.com --repair php.pool.restart.

The certificate will not issue

klyrn dns check example.com

Almost always the same cause: the name does not resolve to this server yet, and Let's Encrypt checks. The command prints what the name resolves to now and what this server's address is, side by side. Until they match, the site is served over HTTP and the certificate is retried every ten minutes; you do not have to do anything except fix the record.

The other two causes, in order of how often they happen:

• The clock is wrong. Drift breaks certificate issuance and every two-factor code at the same time. klyrn doctor checks it.
• A name on the site is not on the certificate because it did not resolve here when the certificate was issued. Each one is added once it resolves; to ask now, klyrn site ssl example.com, or run the diagnosis and take site.certificate.reissue.

Renewal happens 30 days before expiry, and klyrn doctor reports certificate expiry among its checks, so an expired certificate should never be the first you hear of it.

The domain still points somewhere else

klyrn dns check example.com
klyrn dns records example.com     # if a provider is connected
klyrn dns point example.com       # write the A records at the connected provider

KLYRN is not a nameserver. It never answers DNS queries for your domain, and it does not host zones. It can edit records at a provider that is already authoritative for the name, once you have connected that provider; otherwise you change the record wherever your zone lives.

After a change, the wait is the old record's TTL, not KLYRN. This is why the migration advice is to lower the TTL hours before a cut-over rather than at it.

The database is unavailable

klyrn site diagnose example.com
klyrn db list

The diagnosis separates three things that look identical from the browser:

• MariaDB is not running. The repair is mariadb.start.
• MariaDB is running but this site's database cannot be reached with the credentials the site holds. That is a credentials or grant problem, not a service problem; reset the database password in the panel's Databases page and update the application's configuration.
• The database exists and is empty. Reported as its own finding, because an empty database after an import or a restore is a different problem from an unreachable one.

One database has one user, granted on that database only, from localhost. Root stays on the Unix socket, so nothing on the network can reach it.

A backup failed

klyrn jobs                  # what ran, and what failed
klyrn job 118               # the steps of one job, and the error on the step that failed
klyrn backup list example.com

A failed job keeps its steps and its log. The step that failed carries the error, and every step after it is recorded as cancelled rather than left looking as though it never ran.

The three causes worth checking first:

• Free space. A backup is written locally before it is copied anywhere. klyrn doctor checks disk space and inodes.
• The account is over its disk limit, in which case new archives are refused with the limit, the usage and the age of the measurement in the message. See disk nearly full.
• The off-site destination. The local archive can succeed and the copy still fail. KLYRN says when an off-site copy was left behind rather than reporting the backup as wholly done.

A backup counts only after it has been verified: the archive is listed back and every SHA-256 in its manifest is checked. A job that failed verification did not produce a backup you can rely on, and KLYRN will not pretend otherwise.

An update failed

klyrn update status
klyrn update --check

A failed update has already put itself back. The previous release stays on disk, so rolling back is the same symlink move as going forward; if core, the panel, nginx or health does not come back after the switch, KLYRN restores the previous release and the state snapshot it took before the migrations, and reports the update as failed rather than as done. The server you are looking at is the one you had.

If it refused before installing anything, that is the design working. It verifies the manifest's signature against the key built into the running binary, the artefact's SHA-256, the version the downloaded binary reports about itself, and whether this server is new enough to upgrade at all. The message names which of those failed. The seven refusals, and their exact wording.

One of them is not a fault: this release requires at least … means you are more than one step behind and need an intermediate release first.

The disk is nearly full

klyrn doctor                        # disk space and inodes, server-wide
klyrn account quota                 # every account's usage against its limit
klyrn account quota acme --measure  # measure one now rather than wait

Check inodes as well as bytes. On a server full of small files inodes run out first, and the error when they do names no file at all, which is why the doctor reports them separately.

Past its limit, an account is refused uploads, extractions, copies, new archives, restores and new sites. Deleting, renaming and editing stay allowed on purpose: deleting is the way back under the limit, and an account that cannot edit wp-config.php because it is 2 MB over is a support ticket, not enforcement. A refusal schedules a fresh measurement, so “delete something and try again” works within about a minute.

A disk limit is a boundary, not a filesystem quota. A script the account runs itself writes through the kernel, not through KLYRN, so it can pass the limit; the next measurement will show that it did. What that means, precisely.

WordPress is broken

klyrn wp health example.com
klyrn site logs example.com --kind error --lines 200

Three shapes, and they need different answers:

Blank page, HTTP 200, no error

A page with nothing in it still answers 200, which is why this hides from anything that stops at the status code. On sites created before 0.3.0‑beta.2 the cause was a WordPress download with no themes in it; that is fixed for new sites, and an existing one is repaired by installing a theme or re-creating the site. KLYRN deliberately does not re-download WordPress core over a live site to fix it: that would be worse than the defect.

Blank or broken after an update

KLYRN does not roll WordPress updates back, because the database may already have migrated and putting the files back would leave the two disagreeing. Restore the pre-update backup, which the failed job names. The update policy takes that backup first for exactly this reason.

403 on every page

Either the site is suspended (the diagnosis says so, and who did it) or the file permissions are wrong, in which case it offers site.permissions.repair. That re-owns the site tree to the account and sets directories to 750 and files to 640. It refuses any root outside /home/ and never changes a file's contents.

klyrn wp health returns ten signals, each naming something specific rather than a score. WordPress covers them and the four hardening actions.

A Node.js application will not start

klyrn site diagnose example.com
klyrn app logs example.com --lines 200
klyrn app show example.com

Each application is a sandboxed systemd unit on a private port behind nginx, with a memory ceiling. The diagnosis reports the unit's state and distinguishes “down” from “restarted recently”: a unit that keeps restarting is a different problem from one that never started, and the second is usually the start command or a missing environment variable rather than KLYRN.

• It crashes on boot. klyrn app logs is the application's own output. Fix it, then klyrn app restart example.com, or take the app.restart repair.
• It was killed. A per-account memory limit is enforced by the kernel and reaches Node applications, so a process over it is killed inside that account's slice. Raise the limit or lower the application's memory.
• The last deploy did not health-check. The previous release is still on disk; klyrn app rollback example.com puts it back.

It keeps fixing itself, then breaking again

klyrn health
klyrn health --events

The health engine runs thirteen checks on a staggered schedule, from every 30 seconds for the services to every six hours for certificates, and a failed check gets a bounded repair (restart the unit, restart application units that are in the failed state) and nothing else. It never deletes data, kills customer processes or changes firewall rules.

The circuit breaker allows three repair attempts per check per thirty minutes. After that it stops and records “automatic repair paused: 3 attempts in 30 minutes did not hold. Needs a human.” That message is the point at which the engine has stopped guessing and wants you. klyrn health --events is the record of every attempt with its reason, action, result and duration, and it is the first thing to read when something has been flapping.

A check that returns to healthy closes the circuit and gets a fresh budget.

Nothing is obviously wrong and it still is not right

klyrn doctor --verbose            # the evidence for every check, not only the failures
klyrn doctor --bundle             # the same, plus a redacted support bundle

--bundle has to be run as root. It writes to /tmp/klyrn-support-<time>.tar.gz unless --out says otherwise, and it never reads the master key, any private key, the panel database or a customer's files. Everything it does read is scrubbed on the way in, and the bundle's own README says how many values were removed and of what kind, so the redaction is something you can check rather than trust. The same thing is in the panel under Settings → Diagnostics; bundles are removed from the server after six hours.

Read the bundle before you send it. It is your server.

Then report it through the account you installed with at my.klyrn.com, with what you did, what you expected, what happened, and the doctor's output. Where to get help says what nobody from KLYRN will ever ask you for.

Deeper reference: Troubleshooting for what each probe examines and the full repair table, and the CLI reference for every command group.