Troubleshooting and logs

Find the logs, read a crash report, report an issue, raise the memory ceiling, and fix common problems.

When something goes wrong, Oxys DB Studio shows an error you can act on and keeps working: a failed operation never takes the application down with it. This page shows where to look next.

The error dialog

A failed operation opens a dialog that says what failed and suggests what to check: credentials, reachability, a duplicate unique key, a file path, the Read-Only Lock. Show details shows the technical message, Copy to clipboard copies it for a report, Ask AI helper (when the AI Helper is set up) asks the assistant how to fix it, and Report this problem builds a bug report you read before sharing (see Reporting problems).

Find the logs

Choose Help › Open Logs Folder. The folder holds:

File	Content
`log.txt`	One timestamped line per event: failed commands, connections opened and closed, servers lost and found again. Credentials are masked. Rotated by size into `log.txt.1` … `log.txt.5`.
`global_exception.log`	Every unexpected internal error, with its backtrace.
`updater.log`, `install.log`	What the updater did.

By default the logs are in .oxysdb in your home folder; OXYSDB_LOG_DIR moves them (see Preferences). Help › About Oxys DB Studio shows the exact paths. The logs are never sent anywhere.

After a crash

If an earlier run recorded an unexpected error you have not seen yet, the Crash Log dialog opens at the next start. It shows that part of the log; Open Crash Log opens the file and Copy copies the text. Either answer marks it as seen, so the next start says nothing until a new error happens.

If the application itself closed unexpectedly, it wrote a redacted crash report in the crash-reports folder of the logs folder, and the next start asks “Oxys DB Studio closed unexpectedly. Review and report?” instead: Review and Report… opens the report, Not Now dismisses it. Nothing is sent either way.

Report an issue

Help › Report a Problem… builds a single report you can post as an issue (see Reporting problems). To send the raw files instead:

Choose Help › Report a Problem…, then Save Logs Folder….
The application writes a report folder on your computer (by default under issue-reports/<date-time> in the data folder) and shows it: system.json (version, operating system), the logs with credentials masked, and your connections as URIs without passwords.
Review the files and remove anything you do not want to share.
Open the issue tracker from the dialog and attach what you choose. Nothing is sent by the application itself.

For a security problem, do not open a public issue: see Security.

Memory ceiling

Heavy operations (imports, exports, schema analysis, compare…) stop when the application’s memory goes over a ceiling, 4 GB by default. Only the job that made memory grow is stopped and reported as failed; the application and every other tab keep working.

To raise or lower it, before starting the application:

set the OXYSDB_MAX_MEMORY environment variable, for example OXYSDB_MAX_MEMORY=8g; or
add a line max-memory = 8g to runtime.options in the settings folder.

The environment variable wins over the file. The value is read at start-up, so restart after a change. The smallest accepted ceiling is 256 MB.

Common problems

Problem	What to do
Cannot connect (the connection times out)	Check that the server runs and is reachable from this computer (firewall, VPN, SSH tunnel). See Connections.
Authentication failed	Check the user name, password and authentication database in the connection’s settings.
A write is refused immediately	The connection has the Read-Only Lock. Remove it in the connection’s settings if the write is intended.
An operation stopped with “memory ceiling”	Narrow it (a query, fewer documents, a smaller sample) or raise the ceiling as above.
IntelliShell does not start	Check Edit › Preferences › IntelliShell: the bundled mongosh is used by default; a custom executable path must exist.
Export to BSON or import of a dump fails	Check Edit › Preferences › External tools › MongoDB tools for `mongodump` and `mongorestore`.
Oracle, Db2 or Sybase source not available	Install the vendor’s client and point Edit › Preferences › External tools › SQL Drivers at it.
The update check, AI Helper or Team Sharing fail at once	Offline mode may be on, or a proxy is needed: see Edit › Preferences › Advanced settings › Network and its Test connectivity button.
“Settings recovered” at start-up	A settings file was unreadable; it was moved aside and the defaults are used. The log names the file.
Saved connections are missing after enabling the key store	Enter the master password when asked at start-up: until then the key store stays locked.
A tab says its connection was lost	The server went away. The tab reconnects when the server comes back; refresh to load the data again.

For agents and scripts

The same information is available as commands, from the command line or the MCP server: app.log-files (paths of the logs), app.crash-report, app.memory-ceiling, app.report-issue and app.about.