# 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:

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

Then rerun with a different port if needed:

```sh
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:

```sh
make docs-audit
```

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