Troubleshooting and FAQ.

Starting Plasma#

macOS says Plasma “can’t be opened”. The build has no Apple signature yet. Open System Settings → Privacy & Security and click Open Anyway, or clear the quarantine flag:

xattr -cr /Applications/Plasma.app

Windows shows a SmartScreen warning. The build has no Microsoft signature yet. Click More info, then Run anyway.

Nothing happens when I open a second copy. Plasma allows one instance per profile. Starting it again brings the running window forward, and links and plasma open commands are handed to that window. To run two profiles side by side, start the second with the PLASMA_USER_DATA environment variable set to a different folder.

On Linux the AppImage prints that it starts without the sandbox. Your kernel blocks the user namespaces Chromium’s sandbox needs (common on Ubuntu 24.04 and later). Install the .deb, which ships an AppArmor profile that keeps the sandbox. See Linux.

On Linux Plasma says “No system keyring found”. Install and unlock GNOME Keyring or KWallet and restart. Choosing Store with weak protection works, but the key is one every program on the computer knows.

macOS asks to allow the keychain item after an update. Click Always Allow. See macOS.

Updates#

• No “Restart to update” button, only “Update” or “Download”. That install cannot replace itself: a portable Windows build, an all-users Windows install, a .deb, or a Mac app running from a disk image or a folder it cannot write to. The button opens the download in your browser: the new .dmg or .deb, or the download page for Windows. On a Mac, move Plasma to Applications to get automatic updates.
• “Update refused: …”. Plasma checks a signature and checksums before it installs anything and refused this one. Try Check now later; if it persists, download the installer from the site.
• “The update could not be installed”. After a restart Plasma found it was still on the old version. The message offers Download manually and, on a Mac, names the update helper’s log file. The Mac update helper writes update-helper.log in Plasma’s logs folder, and it is included in a support bundle.
• Settings says the update feed is behind. The published feed advertises an older version than you run, so automatic updates cannot reach you. Download the current build from the site.
• Did I lose my work when the app restarted? Open SQL tabs are saved and come back; the restart lists anything that would be lost before it happens. See What happens to unsaved work.

Connections#

• Read the message. Test stops at the first failing step and explains it. The full list is in Test, errors and diagnosis.
• “Nothing is listening there”. The host answered but refused the port. Check the port number, that the server is running, and that it listens on that address.
• “The server does not allow this login from here”. The server has no rule for your user from this machine (for PostgreSQL, a pg_hba.conf rule).
• A certificate error. Either choose the CA file in Security (CA certificate) or fix the host name; Verify CA and host name requires the certificate to name the host you typed.
• Through SSH, “The jump host could not reach the database”. SSH worked, but the bastion cannot open the database host and port you gave. Remember the host in the form is the one as the bastion sees it.
• My saved password is gone or not saved. Plasma refuses to save secrets when the operating system has no working secret store; see Linux above.
• It keeps reconnecting. Use Stop reconnecting in the connection menu, or turn off Connection lost: Retry automatically.

Editing and queries#

• I can’t edit a cell. Turn on edit mode with the lock button. It stays disabled on a read-only connection, and the grid cannot edit ClickHouse or DuckDB results. A table with no primary key cannot delete rows safely.
• My commit said a row changed. Someone changed it after you loaded it. Your edits are still staged; choose Keep mine or Take theirs per row. See Conflict detection.
• A write was refused. The connection is read-only, or Safe mode is set to Read-only. Both name themselves in the message.
• My query shows “Waiting for the connection”. Another tab is using that connection; statements on one connection run one at a time. Cancel the other one, or wait.
• Cancel says it is still cancelling. The server has not stopped the statement yet. Use Cancel again or Disconnect to stop it. SQLite cannot interrupt a statement that returns no rows for a long time.
• The result stops at 10,000 rows. That is the in-memory cap (also about 32 MiB). Use Export with Whole table or Full result to stream everything to a file.
• psql commands (\d) and COPY FROM STDIN fail. Plasma runs SQL only. Use the sidebar, Import and Export.
• Values look blacked out. Presentation mode is on (masking). Turn it off with the top-bar button.

Backup, restore and import#

• Backup says it cannot find pg_dump. Install the PostgreSQL client tools, or set the folder under Settings → Advanced → PostgreSQL tools. A Version mismatch badge means the tool’s major version differs from the server’s; a pg_dump older than the server will refuse to dump.
• Restore needs the database to exist. Create it first, then choose it as the target.
• An import changed nothing. It runs in one transaction; any error rolls it all back and the dialog shows the error. A cancelled import also imports nothing.

MCP and AI#

• The MCP status says the port is in use. Pick another port in Settings → MCP server and update your client’s config.
• My client gets 401. The token is wrong, or you regenerated it. Copy the snippet again.
• A browser-based tool gets 403. Plasma rejects any request that carries an Origin header; use a local client.
• A tool says “does not allow … for AI tools”. The connection’s access level is too low. Change it in the MCP section.
• The stdio bridge says “Open Plasma and turn on the MCP server in Settings”. Plasma is not running or the server is off.
• The assistant can’t see my tables. Schema context is off, or the connection is tagged Prod and you have not opted in. The line under the message box shows Schema: off. See What is sent.
• The agent does nothing with a local model. Choose a model that supports tool calling.

FAQ#

Is Plasma free? Yes. It is open source under the Apache-2.0 license, and you do not need an account.

Which databases? PostgreSQL, MySQL, MariaDB, SQLite, ClickHouse, DuckDB, Redis and OpenSearch.

Do I need AI? No. It is optional and off until you add a key or a local model.

Where are my settings and history? In a local database in Plasma’s user-data folder on your computer. See what leaves your machine.

How do I report a bug? Help → Report a Bug, and attach a support bundle you have reviewed.