Troubleshooting

Start with the smallest failing layer. A bad connection cannot be repaired in an alias, and a correct map cannot place the player until an integration identifies the room.

No text appears and the connection times out

• Confirm the saved host and port against the MUD's current website.
• Enter only the host name, without a URL scheme or path.
• Check whether a firewall, VPN, or restricted network blocks the port.
• Ask whether the MUD is currently online.

TLS or certificate failure

Confirm that the MUD actually offers TLS on that port. Keep certificate verification enabled. If the MUD deliberately uses a self-signed certificate, verify that instruction through a trusted channel before accepting the risk.

The connection opens, then closes

Read the last server text for a login rejection or maintenance notice. Temporarily remove commands sent on connect to rule out a stale login sequence. Reconnect with a raw log when the disconnect appears to be a telnet or compression problem.

If letters or symbols are wrong, edit the server's Encoding only after checking what the MUD uses. The MUD's negotiated encoding overrides the saved fallback.

If colors, cursor movement, or line breaks are wrong, reproduce with raw logging enabled and keep both the readable and .raw.log files. A screenshot shows the symptom; the raw log shows the bytes that caused it.

If text is too narrow or too small, check terminal line length, font, and size under Settings → Preferences.

The MUD may have enabled telnet echo suppression, the normal signal for a password prompt. Use the reveal control only in private, and wait for the MUD to restore ordinary echo. If the MUD leaves suppression enabled by mistake, reconnect before considering the compatibility setting that disables automatic masking.

Open the profile offline, then check the tester, enabled switch, parent folders, pattern status, and Script body. For a full sequence, see Organize and troubleshoot automations.

If every saved automation vanished, confirm that you opened the intended server and did not start a development build, whose data lives under Documents/smudgy-dev.

Open its Installed detail rather than its generated automation. Look for:

• disabled state;
• permissions not yet accepted;
• an update held back for added access;
• a required newer smudgy version;
• a missing or incompatible dependency;
• an integrity or download error;
• a JavaScript or TypeScript load error.

Do not remove the sandbox as a generic repair. A package that cannot work within its documented permissions needs an author fix or a clearly explained permission change.

An empty editor can mean no maps have been installed, imported, shared, or created for that server. A visible map without a player marker means the MUD-specific integration has not set a location. A wrong marker often means duplicate external ids, the wrong area being active, or a stale integration.

Use Sync in the Map Editor when cloud status reports a failure. Check the area list's active switches and server scope before editing room records to compensate for an identification problem.

The diagnostic file is Documents/smudgy/smudgy.log (or smudgy-dev/smudgy.log for a development build). Preserve it before launching repeatedly if it contains the failure. Back up the data directory before hand-editing JSON.

When reporting a reproducible problem, include the smudgy version, operating system, exact steps, expected and actual result, and the smallest relevant sanitized log. Add a screenshot for visible state, but include text for error messages so it can be searched.

Do not delete the whole data directory. Close smudgy, make a full copy, and then isolate one server or one suspect automation/package at a time. Restoring from a known backup is safer than trying several destructive fixes on the only copy.