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 failed, and sorts the findings with the critical ones first. Both name a cause and print the evidence they used.

A diagnosis offers a repair by name when it has one. There are six. 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.

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

The site does not load at all

klyrn site diagnose example.com

Read the first finding. It is usually one of four things:

• The site is suspended. The finding says so, and who suspended it. Run 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.
• 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. 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. For a PHP site that means the FPM pool, and for a Node site the application. The diagnosis names which of four states it is in.

If it started right after you changed a PHP setting, you may be on a build older than 0.3.0‑beta.4. That build had a defect that left the pool serving through a socket nothing could reach. Run 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 beside this server's address. Until they match, the site is served over HTTP and the certificate is retried every ten minutes. Fix the record and wait.

The other two causes:

• The clock is wrong. 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, run 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.

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 answers for a domain only when this server is its nameserver. Otherwise connect the provider that is already authoritative for the name, and KLYRN edits records there. Or change the record wherever your zone lives.

After a change, the wait is the old record's TTL. The migration advice is to lower the TTL hours before a cut-over.

The database is unavailable

klyrn site diagnose example.com
klyrn db list

Three causes 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. Reset the database password in the panel's Databases page and update the application's configuration.
• The database exists and is empty. This is its own finding. An empty database after an import or a restore is a different problem from an unreachable one.

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

The step that failed carries the error. Three causes are 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. New archives are refused, and the message carries the limit, the usage and the age of the measurement. 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.

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.

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. It also restores the state snapshot it took before the migrations, and reports the update as failed.

It may have refused before installing anything. KLYRN verifies the manifest's signature against the key built into the running binary, and the artefact's SHA-256. It also checks 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 names no file. 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, because deleting is the way back under the limit. A refusal schedules a fresh measurement, so deleting something and trying again works within about a minute.

A disk limit is a boundary. It is not a filesystem quota. A script the account runs itself writes through the kernel, 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

Blank page, HTTP 200, no error

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. Repair an existing one by installing a theme or re-creating the site. KLYRN does not re-download WordPress core over a live site to fix it.

Blank or broken after an update

A scheduled update is not rolled back. One started from the panel is, from its backup. 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.

403 on every page

The site is suspended, and the diagnosis says by whom, or the file permissions are wrong. For those 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, and each names something specific. 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

The diagnosis reports the unit's state and tells “down” from “restarted recently”. A unit that keeps restarting is a different problem from one that never started. The second is usually the start command or a missing environment variable.

• 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. The kernel enforces a per-account memory limit, and it reaches Node applications. 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, from every 30 seconds for the services to every six hours for certificates. A failed check gets a bounded repair: restart the unit, or restart application units that are in the failed state. 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.” klyrn health --events records every attempt with its reason, action, result and duration. Read it first 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. It never reads the master key, any private key, the panel database or a customer's files. Everything it does read is scrubbed, and the bundle's README says how many values were removed. The panel offers the same under Settings, then Diagnostics. Bundles are removed from the server after six hours.

Read the bundle before you send it.

Then report it through the account you installed with at my.klyrn.com. Include 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.

Troubleshooting covers what each probe examines and the full repair table. The CLI reference covers every command group.