Debug log

How do I turn on Mel's debug log? Start Mel with the environment variable MEL_DEBUG_LOG set to a file path. Mel then writes a log to that file while it runs: what it was doing, slow frames, and errors from the libraries underneath it. Send that file with your bug report so we can see what happened on your computer.

The debug log is off by default and costs nothing while it's off.

Steps

Quit Mel first, then start it from a terminal window with the variable set.

macOS

MEL_DEBUG_LOG="$HOME/mel-debug.log" /Applications/Mel.app/Contents/MacOS/mel

Linux

MEL_DEBUG_LOG="$HOME/mel-debug.log" mel

If mel isn't on your PATH, run it from the folder you unpacked it into: MEL_DEBUG_LOG="$HOME/mel-debug.log" ./mel.

Windows (Command Prompt)

set MEL_DEBUG_LOG=%USERPROFILE%\mel-debug.log
"%LOCALAPPDATA%\Programs\Mel\mel.exe"

Windows (PowerShell)

$env:MEL_DEBUG_LOG = "$env:USERPROFILE\mel-debug.log"
& "$env:LOCALAPPDATA\Programs\Mel\mel.exe"

If you use the portable zip, run mel.exe from the folder you extracted instead.

Then:

1. Do what causes the problem, once.
2. Quit Mel.
3. Open the log file, read it, and attach it to your email to hello@openmel.dev (or the contact form), with the steps from Getting help.

What the log contains

• One JSON record per line.
• Mel's own records, and messages from the libraries Mel is built on (the window, the graphics, the clipboard).
• Slow frames, with the part of Mel that was running.

Anything that looks like a key or token is masked before it's written. Mel never writes your clipboard, prompts or command output to it. Messages from the libraries can still name a file path or a web address, which is why you should read the file before you send it.

More detail

For a deeper log, also set MEL_DEBUG_LOG_LEVEL to debug (or trace) the same way. It grows quickly, so turn it on only while you reproduce the problem.

The support log

Mel also keeps a small support log that holds only sizes, counts and short fixed codes from Mel itself, never your text. It's at most about 512 KB (the file and one older copy).

• Windows: on by default, at %APPDATA%\mel\support.log.
• macOS and Linux: off unless you start Mel with MEL_SUPPORT_LOG=1; it's then at ~/.local/share/mel/support.log.
• MEL_SUPPORT_LOG=0 turns it off anywhere.

Exporting a conversation

For an agent problem, Export Conversation in the command palette writes the conversation to a .zip file. With MEL_DEBUG_LOG set, the export also includes the end of the debug log. Before you share it, tick Mask secret-looking strings (keys, tokens) and Replace absolute paths and your home folder. See Conversation management.

FAQ

Where is Mel's log file? Wherever you point MEL_DEBUG_LOG. With the variable unset there is no debug log, only the small support log (on Windows by default).

Does the debug log slow Mel down? Barely. It's off unless you set the variable, and even on it writes only important messages unless you ask for debug or trace.

Is it safe to send? Keys and tokens are masked, and your prompts, clipboard and output aren't in it. It can contain file paths, so read it first.

Why is there no log file? Mel was probably started from the Dock, the Start menu or an app launcher, so it didn't get the variable. Quit Mel and start it with the terminal command above.