Troubleshooting

This page covers current supported failure symptoms and checks. It intentionally does not preserve incident history; use it as an operational/debugging guide.

Build Problems

missing Franny binary

• Run make franny.
• Confirm third_party/franny/franny exists.

missing tool: mads

• Install MADS and make sure mads is in PATH.
• Re-run make mms-com-hatabs.

MMS HATABS end exceeds stable BASIC limit

• Run make mms-abi-check and inspect build/mms-abi.json.
• The HATABS resident end must stay under the configured BASIC-safe ceiling.
• Avoid adding resident MMS code without checking size impact.

ATR inspection fails

• Rebuild with make mutineer-atr.
• Inspect build/mutineer-atr-manifest.json for missing root, CORE, DATA, ASCII, ATASCII, or MAIL files.

Altirra Launch Problems

Altirra starts but the expected 850/modem config is absent:

• Check tools/altirra/4.40/Altirra.ini.
• Check the generated profile under results/altirra-850/.
• Portable INI sections must be rooted under User\Software\virtualdub.org\Altirra.

Altirra cannot find mounted files:

• Confirm .wine-altirra/drive_z maps to the workspace.
• Confirm MUTINEER_ATR points to an existing ATR when overriding.
• Confirm third_party/SDX450_maxflash8.car exists unless MUTINEER_USE_SDX=0.

Host port is already busy:

ss -ltnp | grep 6507 || true
pkill -f Altirra || true
wineserver -k || true

Then rerun with a different port if needed:

MUTINEER_MODEM_PORT=6517 make altirra-850-run

Caller Connection Problems

No HIT <RETURN> prompt:

• Confirm the ATR booted through AUTOEXEC.BAT.
• Confirm RHND850.COM and MMS.COM loaded.
• Confirm the BBS reached WFC.
• Enable debug output with MUTINEER_ALTIRRA_DEBUG=1 for tests.
• Increase MUTINEER_CONNECT_DELAY for slow boot/test hosts.

Telnet connects but input looks wrong:

• Confirm MUTINEER_TELNET and MUTINEER_TELNETLF match the client.
• Try the default scripted telnet client before changing line endings.
• Use MUTINEER_LINE_ENDING=crlf unless testing another client mode.

Connection rate is wrong or too slow:

• Set Altirra modem rate with MUTINEER_CONNECT_RATE.
• Set MMS R: baud code before MMS_MOPEN using USR(MBAUD,code) or POKE MBASE+156,code.
• Keep host modem rate and Atari R: code aligned for speed-sensitive tests.

BASIC Or MMS Problems

BASIC fails after MMS loads:

• Run make mms-abi-check.
• Check the HATABS MMS_END value in build/mms-abi.json.
• Resident footprint must leave enough low memory for BASIC.

Module switch returns to WFC:

• The module likely failed handoff validation, MMS_MOPEN, or carrier check.
• Check MMS_LAST_ERROR, MMS_LAST_CIO, and latest emulator/test transcript.
• Confirm MMSAPPS.DAT matches source/config/MMSAPPS.CFG.

Carrier loss does not return promptly:

• Confirm the module checks MMS_CONN_STATE at prompt/input boundaries.
• Use the disconnect-watchdog build only for diagnostics: make mutineer-disconnect-test.

D: HATABS behavior fails:

• D: wrapping is guarded and experimental.
• Production acceptance uses the core HATABS probe set, not D: probes.
• Use make mms-hatabs-probe-d only when working on D: wrapping.

File, Message, And Door Problems

No message bases:

• Run INIT offline and create a message base.
• Confirm D1:>DATA>MSGBASE.CFG points to the intended root.
• Confirm MESG?.MET, MESG?.DAT, and MESG?.IDX exist.

No file areas:

• Run INIT or FILEMGR offline and create a file area.
• Confirm FILE?.MET, FILE?.DAT, and FILE?.IDX exist.
• Confirm upload paths are valid SDX paths.

Door unavailable:

• Confirm the D1:>DATA>DOORS.CFG row has the right filename/path.
• Confirm the door disk/path is mounted where the row points, commonly D3:.
• Missing door files should report DOOR UNAVAILABLE. without dropping carrier.

XMODEM hangs:

• Confirm XFER entered raw mode and returned from raw mode on exit.
• Keep XMODEM paths within the current handoff path length.
• Use make mutineer-xmodem-test for scripted reproduction.

Docs Problems

Run:

make docs-audit

The audit checks required docs pages, local Markdown links, documented Make target names, and documented tools/*.py references.