Logs and the diagnostics bundle

When something goes wrong in Alcuin itself, a diagnostics bundle gives a bug report what it needs: versions, the last lines of Alcuin’s log, and the names of any crash dumps. It is one text file, and you read it before anyone else does.

Save a diagnostics bundle

1. Choose Help → Save Diagnostics Bundle…. In the command palette (⌘⇧P on macOS, Ctrl+Shift+P on Windows and Linux) the same command is Save a diagnostics bundle….
2. Choose where to save it. The name Alcuin suggests is alcuin-diagnostics- and the date in UTC, such as alcuin-diagnostics-2026-11-07.txt.
3. Click Save. A message says Diagnostics saved to and the file name.

The log is kept in a file, so its lines are still there after you quit or Alcuin crashes. You can save the bundle after you start Alcuin again.

On macOS and Linux, Alcuin writes the file readable only by your user account.

What is in it

The file has four parts, in this order:

Part	What it holds
The first three lines	Alcuin’s version, and whether it is a packaged build; the Electron, Chromium and Node versions; the operating system, its release, the processor architecture and the memory
## Settings	The app’s small settings file: whether you receive pre-release builds, the window’s background color, and the paths of the project folders you have chosen in Alcuin
## Crash dumps	How many crash dump files are on this machine, and their file names
## Log	The last 500 lines of the log file, each with its time

The log says what the engine and the app did. For the engine: connections opened, lost and restored, by connection name, with the server’s version; connections locked and unlocked; changes applied, by how many statements; and the reason a connection was lost. A request that fails in a way Alcuin did not expect is logged with its name, its code and its stack trace, which is what a fix needs most, but not its message, because a server’s message can quote a value from your query.

The settings you choose in Settings, such as Rows per page or the Safety rules, are not in the bundle.

What it never contains

• Passwords, SSH passphrases, the assistant’s API key or agent tokens. Alcuin keeps the first three encrypted with your operating system’s key store, and agent tokens only as hashes. The bundle reads none of them.
• Your connection profiles. The log names a connection by its name, and an error message can name a host and port, such as 10.0.0.5:5432.
• The crash dumps themselves. Only their names are listed.

Before it writes the file, Alcuin replaces anything shaped like a credential with [redacted]:

• the value after password, passphrase, token or secret followed by = or :
• the password in any URL of the form scheme://user:password@host

Paths on this machine do appear: the project folders under ## Settings, and Alcuin’s data folder, which the engine logs when it starts. Both usually include your user name. Nothing filters query text out of the log: Alcuin redacts credentials, not query text. A crash in the engine is logged with its message, and some warnings keep their message as it was, such as a lost connection, an SSH error or a failed read of a result. Such a message can name a host or quote part of a query or a value from your database. Read the file before you share it, and remove what you don’t want to share.

Where the logs are

Alcuin writes its log to a file on this machine. Choose Help → Open Logs Folder to see it.

System	Folder
macOS	~/Library/Logs/alcuin
Linux	~/.config/alcuin/logs

The log is main.log. When it reaches 2 MB, it replaces main.old.log and starts again, so the two together stay near 4 MB. Every line passes the same redaction as the bundle before it is written, so credentials in the shapes above never reach the file. Only your user account can read it, and Alcuin never uploads it.

To watch the log as it happens, start Alcuin from a terminal. The engine’s lines start [engine]. Most of the app’s own lines start [shell]. Both print there:

System	Run
macOS	/Applications/Alcuin.app/Contents/MacOS/Alcuin
Linux, from the .deb	/opt/Alcuin/alcuin
Linux, AppImage	./Alcuin-<version>.AppImage, from its folder

Where the crash dumps are

When a part of Alcuin crashes, Electron writes a crash dump on this machine. Alcuin never uploads it. The dumps are in a Crashpad folder in Alcuin’s data folder:

System	Folder
macOS	~/Library/Application Support/alcuin/Crashpad
Linux	~/.config/alcuin/Crashpad

A dump holds part of the crashed process’s memory, which can include data you had open. Attach one to a report only if a maintainer asks for it, and only if you are comfortable sharing it.

Report a problem

Get help says where to report a bug and what to put in the report. Save the bundle first, and read it before you attach it.

The bundle is never sent by Alcuin itself: only you share it. Privacy lists everything Alcuin sends anywhere.