When something is wrong

This handbook covers MixLab through the mix command line. If you would rather work in a graphical interface, you already have one: every installer places the MixLab window beside the command line. Both drive the same MixEngine underneath, so everything in this handbook still applies.

Start here

mix doctor

It examines the machine and says what is wrong with it. It reports and repairs nothing unless you ask, and it exits non-zero when it found a problem, so a script can ask too.

mix doctor --repair

Repairs everything that can be repaired. Anything inside MixEngine's own home is fixed at once; anything needing an administrator is queued, shown to you, and then granted in one prompt for the whole batch. --yes skips the confirmation before that prompt.

The four questions people actually have

"Is anything running?"

mix status
mix service list

status is the daemon: its version, its home, and what it is supervising. service list is the row per service with what each one is doing.

"Why does this name not open?"

mix domain status blog.test

Four facts, answered separately rather than as one verdict: whether the name is declared, how it is routed, whether it resolves on this machine right now, and whether anything answers on it. The one that is no is the one to fix.

"Why is the padlock not green?"

mix cert status
mix cert ca-status

cert status opens a real connection and reports the certificate that was actually presented, which is the only thing a browser ever sees. ca-status says what the authority is. If the authority is not trusted, mix doctor --repair is what puts it back.

"Which PHP is this, and why?"

mix runtime resolve php

The version this directory gets, and which of the four sources decided it. That second half is what you want when the answer is not the one you expected.

Reading the logs

mix service logs caddy --follow
mix service logs mariadb@main -n 200

--follow survives the service crashing and being restarted: what is being followed is the service, not one run of its process. The daemon's own log is logs/daemon.log inside MixEngine's home.

For a long operation, such as an install or a blueprint apply, the job is where to look:

mix job list
mix job status <id>
mix job logs <id>

mix job logs only answers for a job that runs somebody else's program, which today means a blueprint running its own scaffold command. Everything else a job does is reported as progress and as a result, and this says so rather than pretending output was lost.

Common situations

A port is already in use. Something else on your machine has it. mix service create --port picks another for a new service; for one that exists, delete it and create it again on a different port. The data directory is kept.

The daemon will not start. Read logs/daemon.log in the home. mix status --no-autostart asks whether one is running without starting one, which is the right question when you are diagnosing rather than working.

A command needs a version that is not installed. MixLab says so and names the exact mix runtime install command to type. When a range was asked for, it cannot know which version satisfies it and points at mix runtime available instead.

Something asked for an administrator and you said no. Nothing is half-applied. mix elevation status shows what is still waiting, and mix elevation grant asks again.

MixLab is using too much disk

mix disk breaks this home down into five categories and says, for each one, what would take it back:

          size      reclaimed by
runtimes  700 MiB   runtime.uninstall — one runtime at a time, and never one a running pool is using
data      1200 MiB  these are your databases, and nothing in MixLab deletes them
logs      40 MiB    `mix cleanup` — 30 MiB in 4 file(s)
certs     < 1 MiB   every site would lose HTTPS until `cert.issue` ran again …
cache     90 MiB    `mix cleanup` — 90 MiB in 12 file(s)
other     310 MiB   packages, generated config, the database

mix cleanup takes back the last two and nothing else. It removes rotated log files (daemon.log.1, a service's current.log.2) and empties the download cache. It does not touch the log files being written right now, this home's crash reports, your databases, your installed runtimes or your certificates: it matches file names rather than sweeping the home, so there is no argument you can give it that would reach them.

--keep-logs and --keep-cache leave one of the two alone. --yes answers the confirmation in advance, which is how a script says yes.

It refuses while another job is running, because emptying the cache would delete the file a download is resuming from. Wait for the job, or cancel it with mix job cancel <id>.

To free more than that: mix runtime list and mix runtime uninstall <runtime> <version> are what reclaim runtimes/, and mix package list and mix package uninstall <package> <version> most of other.

When MixLab itself hits a bug

If the daemon runs into a bug in its own code, it writes a small file into logs/crashes/ inside MixEngine's home. mix doctor tells you one is there as a note, never as a problem, so it does not change the command's exit code.

What is in it: where in MixLab's own source the bug happened, the positions in the program of the functions around it, which version was running and which operating system. That is the whole list. The positions are plain numbers that mean something only for that exact version, and MixEngine's maintainers turn them back into function names.

What is not in it: none of your file paths, none of your site or project names, and no passwords. That is true because of what the file is allowed to hold rather than because something was filtered out of it afterwards. So you can attach one to a public bug report as it is, without reading it first.

The message the crash printed is the one part that can mention a path of yours, so it goes to logs/daemon.log instead. That file is worth sending too, but read it first. See below.

Nothing sends any of this anywhere. There is no server to send it to. The twenty newest are kept and older ones are removed. If you would rather no such file was written at all, put this in config.toml:

[crash]
enabled = false

The daemon log still records that a crash happened.

Reporting a bug

mix doctor --bundle

One archive with everything a bug report needs: what doctor found, this daemon's status, what this machine is, any crash reports, and the tail of the log. --out copies it somewhere of your choosing.

What it deliberately leaves out is named in the archive itself, so nobody has to guess whether a missing section is a redaction or a failure. It is a plain archive: open it and look before you send it anywhere.

Every mix command also takes --json, which is often the fastest way to show somebody exactly what you saw.

This page as Markdown: https://mixnz.github.io/mixlab/en/troubleshooting.md