> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tablepro.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting on Linux

> Saved passwords, SSH tunnels, Kerberos, logs, crash reports and bug reports for TablePro on Linux

Paths here are for the .deb and .rpm packages. The Flatpak bundle keeps the same files under `~/.var/app/app.tablepro.TablePro/`, mapped in [Where the files are](#where-the-files-are).

## Passwords

Native packages keep saved passwords, the MCP server access token and cloud AI API keys in the Secret Service. GNOME Keyring, KWallet and KeePassXC provide this desktop service.

For the bundle, see [Flatpak secret storage](https://docs.tablepro.app/linux/connect.md#flatpak-connections). It needs a working desktop portal and keyring. There is no plain-text fallback when secret storage fails.

### Every connect asks for the password

When the Secret Service or Flatpak's Secret portal is unavailable, the password prompt has no **Remember Password** switch. Check for a desktop keyring:

```bash theme={null}
busctl --user list | grep org.freedesktop.secrets
```

No line means none is installed or none can start. Install one, then log in again:

* GNOME and most other desktops: `gnome-keyring` (`sudo apt install gnome-keyring`, `sudo dnf install gnome-keyring`).
* KDE Plasma: KWallet (`kwallet6` on Ubuntu, `kf6-kwallet` on Fedora), which Plasma installs by default.
* KeePassXC: turn on Secret Service Integration in its settings, and leave it running.

The packages recommend one of these, so a normal install has one. A minimal install or a window manager session may not.

### A saved password is asked for again

The keyring is locked. The desktop asks to unlock it when a saved password is read; dismiss that prompt and the app asks for the password instead. A keyring that never unlocks at login usually has a different password from the account, after a password change or with automatic login. Passwords and Keys (Seahorse) or KWallet Manager changes the keyring password to the login password.

After unlocking the keyring, retry the connection and accept the unlock prompt. If saving a newly entered password failed, enter it again with **Remember Password** on.

### MCP and cloud AI cannot read or save a secret

**Preferences > MCP** reports that the access token cannot be read or kept. **Preferences > AI** or the assistant reports the same problem for an API key. Entering a database password at each connect does not restore these features.

**1. Restore secret storage**

If no keyring is running, install or start one as described in [Every connect asks for the password](#every-connect-asks-for-the-password). For Flatpak, also check that `xdg-desktop-portal` and your desktop's portal backend are installed and running, then log in again.

**2. Unlock the keyring**

Unlock it in Passwords and Keys or KWallet Manager. If you dismissed an unlock prompt, retry the operation and accept the prompt.

**3. Retry the affected feature**

In **Preferences > MCP**, click **Try Again**. In **Preferences > AI**, re-enter and apply an API key whose save failed, then retry the request. A key or token already stored does not need replacing after an unlock.

### Saved secret entries

Native-installation entries have these labels in the desktop keyring:

* `TablePro database password for …`
* `TablePro SSH password for …`
* `TablePro SSH key passphrase for …`
* `TablePro MCP access token`
* `TablePro API key for …`

Use these labels when removing saved credentials during a [full reset](https://docs.tablepro.app/linux/install.md#optional-full-reset), which also covers removing Flatpak secrets.

## SSH tunnels

Native packages run the system `ssh` and read `~/.ssh/config`, `~/.ssh/known_hosts` and the SSH agent as a terminal does. For the bundle, check the [Flatpak connection limits](https://docs.tablepro.app/linux/connect.md#flatpak-connections). When a tunnel fails, try the same hop in a terminal first:

```bash theme={null}
ssh -v -J jump.example.com user@bastion.example.com true
```

### Agent sign-in fails

The app uses the agent that `SSH_AUTH_SOCK` names in the desktop session, and `ssh-add -l` lists the keys it holds. When the key works in a terminal and not in the app, the desktop session has a different agent or none: `systemctl --user show-environment | grep SSH_AUTH_SOCK` shows what apps started from the desktop get.

### Unknown host key

The server's SHA256 fingerprint shows before anything connects, even where `ssh_config` says `StrictHostKeyChecking accept-new` or `no`. Compare it with `ssh-keygen -lf` on the server's key, or with what the server's administrator gives you.

### Changed host key

**Review Key** in the connection's banner replaces the entry in `known_hosts`. Under `StrictHostKeyChecking yes` it cannot: run `ssh-keygen -R host`, then click **Retry**. A revoked key is refused, with no way past it in the app.

## SQL Server with Kerberos

**Windows (Kerberos)** uses an existing ticket. `kinit` and `klist` come in `krb5-user` on Ubuntu and `krb5-workstation` on Fedora. For Flatpak, check the [KCM cache and sandbox configuration](https://docs.tablepro.app/linux/connect.md#flatpak-connections) too.

```bash theme={null}
kinit you@EXAMPLE.COM
klist
```

### KRB5KDC\_ERR\_S\_PRINCIPAL\_UNKNOWN

The server's service principal, `MSSQLSvc/<host>:<port>`, is not in the realm the lookup used. It is built from the host and port you typed and looked up in the default realm only. For native packages, check `default_realm` in `/etc/krb5.conf`; Flatpak uses its sandbox configuration. Type the host name the SPN is registered for, not an IP address or a CNAME. A server in another realm works only when your KDC answers with a referral, as Active Directory does inside a forest.

A missing or expired ticket fails the same login: run `kinit` again, then retry.

## Logs and crash reports

Started from the desktop, the app writes its log to the journal:

```bash theme={null}
journalctl --user --boot | grep -i tablepro
```

For a detailed log, quit the app first, since a second launch hands over to the running one and exits. Then start it from a terminal:

```bash theme={null}
RUST_LOG=debug tablepro 2> tablepro.log
```

Before attaching any log, crash report or diagnostic text to a public issue, read it and remove private data. Logs name hosts, databases and tables. Panic messages may include SQL, values or file paths. Keep an unedited copy privately if needed.

Rust panics on the main UI thread write a text report in the [crash report folder](#where-the-files-are). The next launch offers **Show Report**. Nothing is uploaded. These reports do not cover native segmentation faults, native aborts, out-of-memory kills or every worker-thread panic.

### Native crashes

**1. Collect the journal from the crash time**

Start with the user journal command in [Logs and crash reports](#logs-and-crash-reports). For a native crash or an out-of-memory kill, also inspect system messages:

```bash theme={null}
journalctl --boot --since "10 minutes ago" | grep -iE 'tablepro|segfault|out of memory|killed process'
```

Adjust the time to include the crash. If system journal access is denied, ask the system administrator for those messages.

**2. Find crash metadata**

On distributions running `systemd-coredump`, use [coredumpctl](https://www.freedesktop.org/software/systemd/man/latest/coredumpctl.html):

```bash theme={null}
coredumpctl list tablepro
coredumpctl info PID
```

Replace `PID` with the process ID from the row at the crash time. Read and redact the output before sharing it. If no entry exists or `coredumpctl` is unavailable, use your distribution's crash reporter and send the journal, app version and reproduction steps.

A core dump holds process memory and may contain passwords, tokens, SQL and result rows. Never attach one publicly. Send redacted metadata first. If maintainers need a dump, email [hello@tablepro.app](mailto:hello@tablepro.app) to arrange a private transfer, as listed in [the security policy](https://github.com/TableProApp/TablePro/blob/main/SECURITY.md#reporting-a-vulnerability).

## Reporting a bug

Open an issue at [github.com/TableProApp/TablePro/issues](https://github.com/TableProApp/TablePro/issues) with:

* The text from **About TablePro > Troubleshooting > Debugging Information**. **Copy Text** puts it on the clipboard. It holds versions and no connection details.
* Where the app came from (the PPA, COPR, a .deb, .rpm or Flatpak bundle from GitHub Releases, or a source build), the distribution and its version, and the desktop and session: `echo $XDG_CURRENT_DESKTOP $XDG_SESSION_TYPE`.
* The log and newest crash report from the same time, or native crash metadata, after the [privacy review](#logs-and-crash-reports).

## After a downgrade

An app refuses a saved file or history database whose storage format is newer than it understands. This checks the storage format, not the app's version number. An older app may read and change files from a newer app when both use the same format.

[Back up saved work](#back-up-saved-work) before changing versions. When a storage format is too new:

* The connection list shows "Saved connections were created by a newer version of TablePro". **Reset…** moves the file aside, under a name the toast shows, and starts an empty list.
* A connection's saved tabs do not reopen, and a toast says "Saved tabs could not be read", with **Reset**.
* The query history says it could not be read.

Reinstall a version that supports that storage format to reopen the files. Avoid **Reset** if you need the saved work; it starts an empty replacement instead of converting the newer format.

## Back up saved work

**1. Quit before copying**

Close every app window and wait for the process to exit. This stops history and draft writes during the copy.

**2. Copy the app folders**

Copy the config, state and data folders in [Where the files are](#where-the-files-are) to a private backup location. Keep the entire state folder, including `history.db` and any `history.db-wal` or `history.db-shm` files beside it. For Flatpak, copy the entire app folder.

**3. Keep preferences separately**

Save the output of the GSettings command in [Where the files are](#where-the-files-are) with the backup as a reference for your settings. Native keyring items are separate; an export of connections does not include their secrets.

## Where the files are

| Path | Holds |
| - | - |
| `~/.config/tablepro/connections.json` | Saved connections, without passwords |
| `~/.config/tablepro/column_widths.json`, `filter_settings.json` | Column widths and filters per table |
| `~/.local/state/tablepro/history.db` | Query history and saved queries |
| `~/.local/state/tablepro/workspaces/` | Each connection's tabs, and the connections open at the last quit |
| `~/.local/share/tablepro/drafts/` | The text of each SQL editor tab |
| `~/.local/share/tablepro/snippets/` | Custom SQL editor snippets |
| `~/.local/state/tablepro/crashes/` | Crash reports |

These are the default paths. If you set `XDG_CONFIG_HOME`, `XDG_STATE_HOME` or `XDG_DATA_HOME`, use the `tablepro` folder under that location instead.

Preferences are in GSettings: `gsettings list-recursively app.tablepro.TablePro` lists them, and `man tablepro` has the same list.

The Flatpak bundle uses `~/.var/app/app.tablepro.TablePro/config/tablepro/`, `.local/state/tablepro/` and `data/tablepro/` in place of `~/.config/tablepro/`, `~/.local/state/tablepro/` and `~/.local/share/tablepro/`. There, the preferences and a detailed log come from:

```bash theme={null}
flatpak run --command=gsettings app.tablepro.TablePro list-recursively app.tablepro.TablePro
flatpak run --env=RUST_LOG=debug app.tablepro.TablePro 2> tablepro.log
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.