Troubleshooting

Troubleshooting

Two kinds of problems: brewing (your mead) and the app/server. MeadOS has an in-app Troubleshoot section with detailed guidance; this page is a quick reference.

Brewing problems

Fermentation won't start

• Temperature too low (or yeast pitched into hot must). Aim for the strain's range — most mead yeasts like ~18–22 °C.
• Old or un-rehydrated yeast. Rehydrate (ideally with Go-Ferm) before pitching.
• No nutrients / no oxygen. Mead must is nutrient-poor; aerate early and follow a nutrient schedule.
• Give it 24–72 hours before worrying — airlock activity can be slow to appear.

Fermentation stalled partway

MeadOS flags this when gravity goes flat above target, and its stuck-fermentation diagnosis reads your logged gravity and nutrient history to suggest a cause. Common ones:

• Under-nutrition or nutrients added too late (all nitrogen should be in by the 1/3 sugar break).
• High gravity beyond the yeast's alcohol tolerance — check the yeast library for the strain's ceiling.
• High-fructose honey (acacia, tupelo) with a non-fructophilic strain — these stall near the end. Use a fructophilic yeast or restart with one.
• Temperature drop. Warm it gently and rouse the yeast.

It finished too dry / too sweet

• Too dry: backsweeten after stabilising — sorbate and metabisulfite, then honey to taste. Use the backsweetening tool.
• Too sweet / stuck sweet: see "stalled" above; it may not have finished.

Off-flavours

• Hot / solvent (fusels): too-warm ferment or late DAP. Ferment cooler; add nutrients early.
• Sulphur / rotten egg: stressed yeast (low nutrient/oxygen). Usually blows off; rousing and time help.
• Cardboard / sherry (oxidation): too much air exposure after fermentation. Minimise headspace and splashing. The in-app Troubleshoot section covers more.

It won't clear

• Time and cold clear most meads. Cold-crash if you can.
• Pectin haze from fruit: use pectic enzyme (the recipes that need it include it, scaled to volume).
• Fining agents (bentonite, Sparkolloid) for stubborn haze.

App & server problems

The page won't load / "server unreachable"

• Is server.py running? Start it, or check your service (systemctl status meados / launchctl list | grep meados).
• Right address and port? Default is http://localhost:8080; from another device use the machine's IP.
• Firewall blocking the port on the host?

I'm asked for a password unexpectedly

You're connecting from outside the LAN (or "require password on LAN" is on). Check the security card in Settings to see what IP you appear as, and add genuine internal ranges as trusted networks. Remember the password can only be changed from inside the LAN.

Locked out after too many password tries

Login is rate-limited — wait out the temporary lockout, then try again. If you've forgotten the password, you can clear it from inside the LAN (Settings → Server Data) or directly in the database.

Changes aren't showing on another device

Saves are debounced and synced automatically; give it a moment, or use the sync control in the top bar. If a device was offline, its edits re-sync when it reconnects.

A screenshot/label image won't load

Uploaded images live in assets/ — make sure that folder came along in any move/backup. Settings → Unused Images can clean up orphaned files.

Charts or the QR scanner don't work offline

They should — Chart.js and the QR library are self-hosted. If a browser extension blocks them, try another browser. Only Google Fonts loads externally (and falls back gracefully).

Getting help

• The in-app Troubleshoot and Mead Guide sections go deeper on brewing.
• For bugs or questions, open an issue on GitHub.