User guide · Software preview
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
A page shows “Bad gateway” (“The service behind /… did not answer.”) |
The service behind that route (the setup wizard or the Home surface) isn’t running or crashed. | Run maisnie status to see which service is unreachable, then maisnie doctor for why. If you started services by hand instead of with maisnie up, restart with maisnie up, which supervises and restarts a crashed child on its own. |
| You’re locked out of login for 15 minutes | Five wrong passphrase attempts in a row from the same source. | Wait out the cooldown, or run maisnie unlock to clear it immediately (the instance can be running when you do this). |
| You forgot your passphrase | There’s no reset flow, on purpose — see security. | Stop the box, run maisnie unclaim --yes (plain unclaim, with no flag, only prints what it would do and exits without changing anything), restart with maisnie up, and claim it again with a new passphrase. This does not touch your vault or your notes. |
| A connection on Home’s AI model list shows “Not tested yet” and Ask can’t use it | You saved it but haven’t pressed Save and test since, or you edited it since the last successful test — saving a connection again always resets it, even for an unrelated field. | Go to choose a model, press Change on that connection, and press Save and test. Read the plain sentence it returns if it fails (see the rows below). |
| A live test fails: “The provider did not accept the key or sign-in.” | A wrong or revoked API key, or (for the subscription door) a CLI that isn’t actually signed in. | Recheck the key or the CLI’s own sign-in state, then press Save and test again. |
| A live test fails: “Maisnie could not reach it. Check the address, and that it is running.” | A wrong service or server address, a local server that isn’t running, or a network/firewall block. | Confirm the address is exactly right (including /v1 for an aggregator or a local server) and that the server is actually running and reachable from this machine. The “Technical details” disclosure under the sentence often names the specific problem (a refused connection, a name that couldn’t be found, a timeout). |
| A live test fails: “The provider is limiting requests right now.”, “The account has run out of credit or quota.”, or “The subscription has reached its usage limit for now.” | The provider itself is throttling or has cut you off, not a Maisnie problem. | Wait for the provider’s own limit to reset, or use a different connection in the meantime. |
| A live test fails: “The provider turned the request down. Check the model names.” | The model id(s) you typed aren’t ones the provider or aggregator actually offers. | Recheck the model ids in “Which models to use” against what your provider or aggregator actually calls them. |
maisnie up --lan refuses with “the box is not claimed yet” |
You can’t expose an unclaimed box on your network, by design. | Run maisnie up without --lan first, open the loopback URL it prints, and finish claiming. Then re-run with --lan. |
A second maisnie up refuses |
An instance is already running against this data directory. | Check for a running maisnie up in another terminal (or a stale one you forgot about) before starting a new one. The exact message is “another Maisnie instance already holds the lock at <path>“. This is up correctly refusing to run two supervisors against one box, not a bug. |
maisnie doctor reports a port “in use by another process” |
Something else on this machine is already listening on that port. | If you haven’t been through the setup wizard yet (a fresh init, nothing saved), maisnie init --force --port <N> is the easiest fix — it moves all three ports together and there’s nothing saved yet for --force to erase. If the box is already set up (a vault, sources, or an AI connection saved), don’t reach for --force — see the row below — and instead free the port, or edit the three bind ports directly in config/majordomo.json (gatekeeper.bind.port, surface.bind.port, desk.bind.port, plus the two gatekeeper.routes upstream URLs, which must point at whatever you set surface.bind.port/desk.bind.port to). |
maisnie init --force erased my vault choice, my sources, and my AI connections |
init --force doesn’t shift or patch the existing document — it replaces it with a brand-new, empty one. Everything the wizard had saved (the vault path, which sources were on, every AI connection and any API key or app password stored with it) is gone; only the claim (state/gatekeeper/claim.json) and everything else under your data directory’s state/ and logs/ (each connector’s own sync cursor, the run journal, telemetry) survive, because none of it lives in the configuration document. |
Once you’ve been through the wizard, don’t reach for --force to fix a port conflict or any other single setting — see the row above for ports on an already-set-up box. If you do need to start the configuration document over, plan on redoing the whole wizard afterward, and know that any stored secret is gone for good, not just hidden. |
maisnie up refuses: “the surface package is missing from this install” or “connectors/manifest.json is missing from this install” |
A broken or partial install — a piece the wheel is supposed to ship wasn’t actually installed. | Reinstall Maisnie from the wheel you were given; don’t try to work around a missing piece by hand. |
maisnie doctor warns about a missing time zone database |
Some Python builds, notably on Windows, ship no zoneinfo data by default. |
This is a warning, not a failure; Maisnie still runs without it. The tz extra doctor prints does exist — run pip install "maisnie[tz]" in the same environment you already installed Maisnie into (no network trip needed for Maisnie itself, since it’s already installed there; only tzdata is fetched), or just pip install tzdata directly. Either gets you exact time zone handling. |
maisnie doctor warns that file permissions are “advisory only” on Windows |
Windows doesn’t have the same permission-bit model Linux/macOS use. | This is informational, not something to fix — see security for what actually protects secrets on Windows. |
| A calendar note shows the wrong time, or an event lands on the wrong day | Most often a non-IANA time zone name inside the feed itself — an Outlook/Office 365 feed commonly uses a Windows display name ("Eastern Standard Time") instead of an IANA key (America/New_York), which Maisnie cannot look up even with a full time zone database installed — or no time zone database at all on this machine (see the row above). Either way, Maisnie approximates from the feed’s own fixed offset (no daylight-saving adjustment) rather than refuse the event outright, or falls back to UTC when even that isn’t available. |
Open the note itself: whenever Maisnie had to approximate, it says so in a line right under the event (“…was resolved from the calendar feed’s own offset, not a full time zone database, and does not account for daylight-saving transitions”, or “…could not be resolved at all and is shown in UTC as a fallback”). Installing tzdata (see the row above) fixes the no-database case; a non-IANA name from Outlook has no fix on this end — the note explaining why it’s approximate is the whole story. |
| Mail won’t authenticate | Almost always a wrong or revoked app password, two-step verification not turned on for the account yet, or an admin-blocked app password — IMAP’s own login failure doesn’t say which of the three it is, so Maisnie can’t either (see connect your accounts). | Press Save and test on the Accounts step: a rejected login reads “Your mail server did not accept the username and app password. Check both: an app password is not your usual password.” Recheck the app password itself first, then the two-step and admin-block caveats linked above, in that order. |
If nothing here matches
Run maisnie doctor --json and maisnie status --json and read through the output for
anything marked as a failure rather than a note. Most problems this preview can diagnose show up
in one of those two places. When you report a problem, include the output of maisnie --version
too — it names exactly which build you’re running, and that’s often the first thing worth
knowing.