Troubleshooting

Troubleshooting

The application is blocked on first launch

The current pre-1.0 beta is not yet signed with trusted Apple/Windows distribution certificates.

• macOS: move LakeDB to Applications and try to open it once. Then open System Settings → Privacy & Security, scroll to Security, choose Open Anyway and confirm Open. The ad-hoc signature protects the package structure, but it does not replace Apple Developer ID notarization.
• Windows: verify that the EXE came from the official LakeDB release and that its SHA-256 matches. In Microsoft Defender SmartScreen choose More info, then Run anyway.
• Linux: make the AppImage executable.

Do not bypass a warning for a package obtained from another source or with a different checksum. If macOS explicitly says that LakeDB will damage your computer, rather than saying Apple cannot check it, stop and report the exact message.

A restore did not complete

Do not retry repeatedly against important data. LakeDB creates a recovery backup before configuration and SQL restores; copy the path shown by the app, preserve that file and inspect Diagnostics. For SQL restores, verify permissions, free disk space, server version and the selected target schema before retrying in a non-production environment.

A connection fails

Check the host, port, username, server network access, VPN, database permissions, TLS/CA configuration and SSH key/agent. The copyable connection diagnostic distinguishes common DNS, timeout, authentication, TLS and permission errors.

A table cannot be edited

Editing requires a primary key or a complete non-nullable UNIQUE index. It is also disabled for unsupported views, generated-column cases and read-only connections.

Results are truncated

LakeDB limits rows and retained bytes to keep the desktop app responsive. Adjust the result limit in Preferences, or add filters and limits to the query.

Imported passwords are missing

LakeDB tries the supported modern and legacy SQLyog formats, but other clients may use credential storage that cannot be decrypted safely. Review the warning, then enter a password manually or apply shared credentials to the selected rows in the import preview.

Open View → Diagnostics for startup, IPC, connection and SSH events. Reproduce the issue once, copy only relevant entries, remove sensitive details, then use the bug report form.