Troubleshooting

Common issues and quick fixes. If nothing helps — support@ide99.io with a description and the ide99 version (Settings → Updates → About).

Connections

"Could not connect to server"

Most common error. Step by step:

Server running?

# local docker
docker ps | grep postgres

Right port? Postgres defaults to 5432, but Docker often maps to another (5433, 55003, etc.). Check docker ps or your config.
Host reachable?
```
nc -zv localhost 5432
```
Should say "succeeded". On timeout — there's no network/firewall path.
pg_hba.conf? If the server is on another machine, check there's a line like:
```
host all all 0.0.0.0/0 scram-sha-256
```

"password authentication failed for user…"

Check the password (Caps Lock?)
On managed Postgres, sometimes the username needs user@host format (Azure)
Verify the role exists: SELECT rolname FROM pg_roles WHERE rolname = 'youruser';

"no pg_hba.conf entry for host…"

The server refused connection from your IP. Solution depends on server config — your subnet has to be in pg_hba.conf.

On managed Postgres: add your IP to the whitelist in the provider's UI.

"SSL connection has been closed unexpectedly"

Check SSL Mode (see SSL and SSH tunnel)
If using verify-full, ensure the CA certificate is installed
Try prefer for diagnosis (if it works — the issue is in SSL config)

SQL editor

Queries hang

Check Live Ops → Sessions — your previous connection might have locked a table
The Cancel query button in the editor sends pg_cancel_backend. If that doesn't help — pg_terminate_backend via Live Ops.

Autocomplete doesn't work

The schema may not be loaded. ⌘+R in the right tree.
If new tables don't show up — Refresh the tree.
Is "Scan jsonb schemas" enabled in Settings → General? Without it, no jsonb paths.

"relation does not exist"

Schema search_path. By default Postgres looks in public. If your table is in analytics.events — write it explicitly or change search_path:
```
SET search_path TO analytics, public;
```
Check case. PostgreSQL stores names lowercase unless quoted. Orders ≠ orders.

Grid and results

"Query returned 1M rows — UI feels sluggish"

ide99 supports 50M+ rows in the grid, but the first load of a large set takes time.
Consider whether you need all rows. Add LIMIT 1000 for exploration.
Result page size in Settings → General — drop to 500 for snappier interaction.

"Cannot edit cell" / ✏ icon is gray

The query wasn't detected as updatable (multiple tables, aggregate, view without trigger).
Solution: use a specific UPDATE ... WHERE pk = ....

EXPLAIN

"EXPLAIN doesn't work on prod"

With Read-only on, EXPLAIN ANALYZE is blocked (it actually runs the query). Use plain EXPLAIN without ANALYZE.

"Heatmap doesn't light up"

Make sure you picked duration (or rows/cost), not none.
If a node's time = 0 — it's not colored.

JSONB

"JSONB editor shows an error"

Content is invalid JSON. Happens with legacy data or after manual edits.
In Text mode, the validation error is highlighted — fix it.

"Saving JSONB on prod is blocked"

Read-only mode is on. Disable in the connection form → Save.

MCP

"Claude Code doesn't see ide99"

Check Settings → AI / MCP → Status — should be "Listening".
Does ~/.claude/mcp.json point to the right binary path?
After config edit, Claude Code needs a restart (/exit and re-launch).

"Agent hangs after Allow"

Often the query is genuinely long. Check Live Ops — what's running.
The MCP dialog's Cancel button cancels.

Schema tree

"I don't see my table"

Refresh the tree (⌘+R).
Maybe the table is in a schema that doesn't show. Check search_path or use a fully qualified name myschema.mytable.
On managed Postgres, sometimes new tables don't show up immediately due to system catalog caching.

Backups

"pg_dump not found"

Postgres CLI tools aren't installed or not in PATH.
macOS: brew install libpq and add $(brew --prefix libpq)/bin to PATH.
Linux: apt install postgresql-client-17.
Restart ide99 after install.

"Permission denied" during backup

The destination folder isn't writable. Pick another or fix permissions.

ide99 itself

"App feels slow"

Close extra tabs — each holds a result in memory.
Clear history (Settings → Privacy → Clear all local data resets only history and caches; connections and snippets stay — well, see the doc, "Clear all" is broader).
For surgical clearing — delete history.db by hand.

"Window froze"

Most likely a long query is running. Give it 30 seconds.
If it doesn't respond longer — Force Quit and re-launch. Postgres queries continue (closing the client doesn't cancel queries already sent; use Live Ops after restart).

ide99 logs

If something's mysterious — ide99 logs can help:

OS	Path
macOS	`~/Library/Logs/ide99/ide99.log`
Windows	`%LOCALAPPDATA%\ide99\logs\ide99.log`
Linux	`~/.local/state/ide99/ide99.log`

Plain text, open in any editor. No SQL or your data — only app events and errors.

Contact

support@ide99.io — describe the issue, attach:

ide99 version (Settings → Updates → About)
OS and version
Postgres version (if connection-related)
Steps that led to the error
Screenshot if possible

Keyboard shortcuts — what to press.
App settings — where behavior is configured.