Reference
Troubleshooting
Resolve connection problems, missing fields, read-only results and uncertain write outcomes.
The connection test fails
Review the URI or manual fields in Manage connections, then use Test details before saving. Check the host, port, credentials, authentication database and TLS options. For SRV, use a single hostname without a port. For hosted deployments, confirm network access and the provider's connection instructions.
A keychain error is different from a MongoDB connection error. On Linux, an available, unlocked Secret Service is needed to store and retrieve profiles; Windows uses Credential Manager. Correct the keychain issue before trying to save again.
Saved connections do not load at startup
Palryn keeps the window open and shows a storage error with Retry when it cannot open saved connections. If another copy of Palryn is running, close that copy before retrying. If the data directory is unavailable or its permissions have changed, restore access and choose Retry.
A corrupt or unsupported connection file is preserved rather than replaced with an empty list. Keep a backup before restoring a known-good copy; do not delete your saved data to dismiss the error. If more than one error panel is visible, retry each affected view after correcting the underlying problem.
If credential storage is unavailable, unlock or start the desktop keychain and retry the save, test or connection action. Pending credential cleanup is retained for a later retry and does not prevent profile names from loading. Connection strings are not recovered from a plaintext fallback.
A database, collection or field is missing
- Refresh Explorer and confirm the connection is still connected.
- Check the search text and any named-workspace checkbox or regex filters.
- MongoDB permissions can limit what your profile is allowed to list.
- For a missing document field, check server projection as well as column visibility. Expand the document to inspect returned fields.
- Autocomplete and schema analysis are sampled. A field absent from those suggestions can still exist elsewhere.
An empty query result is not necessarily an error. Verify the collection and field names, the filter and the BSON type of the value. "123" is a string; 123 is numeric; an ObjectId or UUID requires its corresponding typed value.
I cannot edit a result
Standard views, aggregation output and Shell output are read-only. Open the underlying collection in a normal query tab. Set server projection to {} and rerun so Palryn has the complete document.
Existing-document writes need a suitable unique _id and a current snapshot. The root ID cannot be edited. Save/discard pending edits, finish any active editor or conflicting background operation, and rerun if the results are marked stale. The disabled action's explanation can identify the remaining blocker.
Check the shield beside the connection or query target. Write protection can block changes to an entire connection or matching databases. If a change is intentional, grant a temporary allowance for the required scope. Expired allowances leave drafts available but prevent saving until writes are allowed again.
A write reports conflict or unknown
Conflict means the loaded original no longer matches the document on the server. Keep your intended changes for reference, inspect a fresh query and reconcile them with the current data.
Unknown means Palryn could not confirm whether an attempted write committed, for example after a connection interruption. Do not assume it failed: inspect the target before repeating an insert, update, rename or restore. Palryn keeps outcome information and does not automatically repeat uncertain writes.
The query stops early or results look old
Page size and result-size budgets limit what is loaded. A byte-limit notice can appear before a page reaches its requested row count. Narrow the filter, return fewer fields or adjust the budget for a subsequent run. Use the pager for more matches.
A changed-query notice means the visible results are from an earlier execution. Rerun to apply the current draft. Shell execution, imports and namespace changes can also invalidate query sessions. An expired session needs a fresh run rather than further paging from the old cursor.
A relation has no display label
- Open Collection tools → Relations… and edit the mapping.
- Check the source path, target database/collection and target field.
- Set a Display template using fields that exist in the target, such as
{name}or{FirstName} {LastName}. - Use the reference preview to check matching documents and their BSON types.
- Rerun the source query to refresh cached labels.
A missing target or empty formatted summary leaves the original value without a label. Failed reads do the same. Automatic labels also require an unambiguous display mapping for that path. See Relations & display templates.
Shell, backup or import fails
Check Settings → Tools for executable paths. The value must identify the executable itself, without arguments. Shell needs mongosh; backups need Database Tools 100.3+. JSON/CSV document transfer does not need either.
For export, choose a new output filename in an existing directory. For JSON import, match the selected array or JSON Lines framing. Ordinary JSON, Extended JSON and supported BSON constructors are accepted; keep field names and ordinary string values double-quoted, and quote string arguments to helpers. Do not include complete Shell commands or arbitrary JavaScript. See supported import formats and constructors. For CSV, match the chosen cell format; plain-text import intentionally produces strings. A backup folder must contain the original database's subfolder, and an archive must be a MongoDB archive.
Check Background jobs for the actual outcome. Imported records or restored collections may already exist after a partial failure; inspect them before starting another import.
My results or edits did not return after restart
Remember restores workspace and query drafts, not result data or unsaved document changes. Run the restored query to fetch results. Turning Remember off clears persisted workspace state; current session state remains only until the process ends.
If Palryn reports unreadable workspace storage, it retains that stored data rather than silently replacing it. Avoid treating a storage error as a successful save of new drafts. Use Settings & shortcuts for the restoration model.
Palryn closes unexpectedly or its window goes blank
In builds with local crash diagnostics, restart Palryn, then open the reports folder in your file manager:
- Windows:
%LOCALAPPDATA%\app.palryn.desktop\crash-reports - Linux:
~/.local/share/app.palryn.desktop/crash-reports, or$XDG_DATA_HOME/app.palryn.desktop/crash-reportswhen XDG_DATA_HOME is set. - macOS:
~/Library/Application Support/app.palryn.desktop/crash-reports
Use Application menu → Issues & discussions or visit Palryn's GitHub community repository to report a problem or start a discussion. This repository hosts issues and discussions; it does not currently contain the application source. Share the latest .json reports along with the steps that led to the problem and whether the entire application closed or only the window content disappeared.
Reports contain app/platform/runtime details, failure categories, code locations and the last recorded result-view action. They exclude query contents, returned documents, connection strings, credentials and arbitrary error messages. Nothing is uploaded automatically. Native backtraces may include build-source paths. Up to 20 reports are retained; you can delete them.
An unclean-exit report can also result from force quit or power loss. Not every failure can produce a stack trace. If opening JSON triggers the problem with the collapsible editor, collect the latest reports after restarting and include the steps and JSON format that reproduced it.