Troubleshooting

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.

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.

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

1. Open Collection tools → Relations… and edit the mapping.
2. Check the source path, target database/collection and target field.
3. Set a Display property that exists in the target, such as name.
4. Use the reference preview to check matching documents and their BSON types.
5. Rerun the source query to refresh cached labels.

A missing target or display property 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 properties.

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 framing and use JSON/Extended JSON rather than BSON constructor syntax. 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.