Collecting a bug report

A good bug report gets fixed faster. Murage can make two kinds of diagnostic file for you, and both are designed to leave your keys and conversations out.

Option 1: export diagnostics for the whole app#

1. Open Settings → General.
2. Find the Diagnostics card.
3. Choose Export Diagnostics… and pick where to save the text file.

The card says what's in it: versions, which settings are on or off, and a redacted tail of the server log. Settings are reported as on or off, not with their values. Murage saves the file readable by your user account only.

Open the file and read it before you share it. It's plain text, so you can check nothing private slipped through.

Option 2: export one incident#

When a bot's turn fails, the error card in the chat can show its tracking details: a diagnostic ID, the turn ID, and technical facts such as the error kind or HTTP status. From there:

• Copy diagnostic ID copies an ID you can paste into your report.
• Export this incident saves a report about that one failed turn: the app version, your system, and a bounded record of what the engine process did around the failure (starting, requests, stopping), without the conversation itself.

An incident report is the most useful thing you can attach when a specific bot keeps failing.

What to put in the report#

• Your Murage version (Settings → General) and your system: Mac (Apple Silicon or Intel), Windows or Ubuntu, and whether you installed a release or run from source.
• The bot's engine and model.
• What you did, what you expected, and what happened instead.
• The exact error message, copied as text.
• Whether the same engine works on its own in a terminal.
• The diagnostics file or incident report, after you've read it.
• A screenshot, if the problem is something you can see.

What never to share#

• API keys, tokens, passwords or sign-in links.
• Your .murage folder, or files copied out of it, such as config.json or databases.
• Your backup recovery key.
• Private conversation text, unless it's needed and you're comfortable with it being public.

If you're running from source and paste logs from the terminal or from ~/.murage/events/, remove anything that looks like a key or token first.

Where to send it

Report bugs on GitHub: github.com/FerroxLabs/murage/issues.

1. Search the existing issues first; someone may have reported it already.
2. Choose New issue, then the bug report form.
3. Fill in the area, what happened, your version and install, and attach your diagnostics.

GitHub issues are public. Anything you attach can be read by anyone.

Security problems

Don't report a security vulnerability in a public issue. Report it privately by following the security policy in the Murage repository.

Before you file

Many problems have a quick fix. Check the page for your area first:

• Engines
• Connected apps
• Startup and ports
• Updates
• Channels
• Voice and calls
• Performance