Troubleshooting¶

When things don't work. This page covers install-time and day-to-day issues that aren't specific to the MCP server.

Install / first launch¶

Windows SmartScreen prompt¶

Octa is not code-signed, so on first launch Windows SmartScreen shows "Windows protected your PC" with only a Don't run button visible.

Fix: click More info in the dialog, then Run anyway. Subsequent launches open without the prompt.

If you want to permanently mark the binary as trusted, right-click octa.exe → Properties → check Unblock at the bottom of the General tab → OK.

Avoid it entirely: install Octa from the Microsoft Store. That build is signed by the Store, so the prompt never appears.

macOS: developer cannot be verified¶

The full message is "Octa.app cannot be opened because the developer cannot be verified", or on macOS 15 Sequoia and later "Apple could not verify Octa.app is free of malware". Octa is ad-hoc signed but not notarised, so macOS Gatekeeper refuses the first launch of a copy downloaded with a browser. The one-line install downloads with curl, which marks nothing as quarantined, so it never hits this.

Fix Option A: Open Anyway:

Double-click Octa.app and click Done (or OK) when macOS refuses.
Open System Settings > Privacy & Security, scroll down to "Octa.app was blocked" and click Open Anyway.
Confirm with your password and Open Anyway once more.

macOS remembers the choice for that copy of the app, so double-click works after this. Control-click > Open did the same up to macOS 14; macOS 15 no longer offers it for apps that are not notarised.

Fix Option B: strip the quarantine attribute:

xattr -d com.apple.quarantine /Applications/Octa.app

macOS: app reported as damaged¶

The full message is "Octa.app is damaged and can't be opened. You should move it to the Trash." with only a Move to Trash button visible.

The app is not actually damaged. This is macOS Gatekeeper's strictest quarantine response for downloaded binaries that aren't notarised. It's particularly common when the archive was extracted with a tool that copies the quarantine flag onto every file inside, or the app was transferred via AirDrop between Macs. The binary on disk is byte-identical to what's published on the releases page.

Fix: recursively clear the quarantine attribute:

xattr -cr /Applications/Octa.app

-cr clears every extended attribute recursively (the bundle has several internal files that each carry the quarantine flag, so the non-recursive form from the previous section isn't enough here). Double-click after running this and the app opens normally.

If you'd rather verify the download first, compare the binary against the SHA-256 listed on the release page before clearing the quarantine.

Linux: build fails on system libraries¶

Linker errors mentioning Xlib / GTK / fontconfig mean system development headers are missing. On Debian / Ubuntu:

sudo apt-get install -y \
  libgtk-3-dev libxcb-render0-dev libxcb-shape0-dev \
  libxcb-xfixes0-dev libxkbcommon-dev libssl-dev \
  libfontconfig1-dev libfreetype6-dev

On Fedora:

sudo dnf install gtk3-devel libxcb-devel libxkbcommon-devel \
  openssl-devel fontconfig-devel freetype-devel

On Arch:

sudo pacman -S gtk3 libxcb libxkbcommon openssl fontconfig freetype2

Linux: AppImage does nothing when double-clicked¶

No window, no error, no dialog. Two causes, in this order:

The execute bit is missing. Browsers save the file without it, and most file managers respond to a double-click on a non-executable AppImage by doing nothing whatsoever. Fix it once:
```
chmod 750 Octa-*-x86_64.AppImage
```
libfuse2 is missing. Releases up to and including 0.17.1 need it, and Ubuntu 22.10 and later, and Mint 22, no longer install it. Later releases carry a statically linked FUSE runtime and are unaffected. On an affected release, either install libfuse2 (libfuse2t64 on Ubuntu 24.04 and newer) or skip FUSE entirely:
```
./Octa-*-x86_64.AppImage --appimage-extract-and-run
```

Whichever it is, run the AppImage from a terminal rather than the file manager while you are diagnosing it. A double-click discards the error; a terminal prints it.

The window cannot be moved or resized, or controls near an edge ignore clicks¶

Octa draws its own title bar by default, which means it also has to provide its own window-moving and window-resizing behaviour. That relies on the desktop honouring two standard requests, and not every window manager does.

The universal fallback is to hand the job back to your desktop. Open settings.toml (see Debug Mode and Reports for the location) and set:

use_custom_title_bar = false

Restart Octa. You get your desktop's normal title bar, and Octa stops managing window geometry entirely. The same switch is Settings -> Appearance -> Window controls in toolbar, but editing the file works even when the interface itself is misbehaving, which is the situation this fallback is for.

Linux: install.sh stops with a permission error¶

./install.sh with no argument installs into /usr/local (/usr on Arch Linux), and neither is writable by a normal user. Either give it root, or give it a prefix you own:

sudo ./install.sh          # system-wide
./install.sh ~/.local      # user-local, no sudo

After a user-local install, make sure ~/.local/bin is on your PATH.

octa command not found¶

The binary isn't on your PATH after install. Three options:

Move the binary to a directory already on PATH: /usr/local/bin/octa (system-wide) or ~/.local/bin/octa (user-local, but make sure ~/.local/bin is in your PATH).
Add the binary's directory to PATH via your shell's rc file (.bashrc, .zshrc).
Invoke Octa with its full path: /path/to/octa file.parquet.

On Windows, the install.bat script adds Octa to your user PATH.

Command not found until you restart the shell¶

Octa installed into a directory that is on your PATH (for example /usr/local/bin), yet octa is "command not found" until you open a new terminal. This is not an Octa bug: your running shell keeps a cache of where each command lives (and of commands it has failed to find), so a brand-new binary is invisible to that session until the cache is cleared. Refresh it without a full restart:

hash -r     # bash
rehash      # zsh

Either of those, or simply opening a new shell, makes octa resolve.

The installed version is older than the one you downloaded¶

get-octa.sh always fetches the newest release, and the installer always writes it to the prefix it prints. If octa --version still reports an older number afterwards, a second copy earlier in your PATH is what you are running: the new binary is on disk, your shell just never reaches it. This is common after switching between a system-wide install (/usr/local/bin) and a user-local one (~/.local/bin), and on Arch, where the AUR package installs into /usr/bin.

install.sh checks for this and warns:

Warning: `octa` still resolves to /usr/bin/octa
  (octa 0.17.0).
  That copy shadows the one just installed and is what you will keep running.

Fix it by removing the older copy, or by putting the new prefix earlier in PATH. To see every copy at once:

type -a octa      # bash / zsh

If the paths already look right, your shell is caching the old one: see Command not found until you restart the shell and run hash -r.

WSL: libEGL / Mesa warnings on launch¶

On WSL, launching the GUI prints a few warnings to the terminal:

libEGL warning: failed to get driver name for fd -1
libEGL warning: MESA-LOADER: failed to retrieve device information
MESA: error: ZINK: failed to choose pdev
libEGL warning: failed to create dri2 screen

These come from Mesa (the Linux OpenGL stack underneath Octa's eframe/egui renderer), not from Octa itself. WSL exposes no native OpenGL GPU, so Mesa fails to bring up its hardware-accelerated Zink (OpenGL-on-Vulkan) path and falls back to software rendering (llvmpipe). The warnings are cosmetic; Octa runs correctly, and for a 2D data-table application software rendering is plenty fast.

To silence the noise, force software rendering up front so Mesa never attempts the Zink/DRI path:

LIBGL_ALWAYS_SOFTWARE=1 octa file.parquet

To make it permanent, add it to your shell's rc file:

echo 'export LIBGL_ALWAYS_SOFTWARE=1' >> ~/.bashrc   # or ~/.zshrc

(GALLIUM_DRIVER=llvmpipe has the same effect.) If you would rather have real GPU acceleration, that requires a working WSLg GPU passthrough: a recent Windows 11, up-to-date GPU drivers, and the libgl1-mesa-dri package installed inside the distribution.

WSL: Open, Save as and Export do nothing¶

The window is fine, octa file.parquet from the terminal works, but clicking Open produces no dialog and no error.

Octa asks the desktop for a file dialog through the XDG desktop portal, falling back to zenity. A default WSL install has neither, and the request then fails in a way that is indistinguishable from you pressing Cancel, so the button appears dead. Octa detects this at startup and puts a note in the status bar.

Install either backend inside the distribution:

sudo apt install xdg-desktop-portal-gtk   # the portal (preferred)
sudo apt install zenity                   # or the simpler fallback

Log out of the WSL session (wsl --shutdown from Windows) and start Octa again. Until then, pass files on the command line:

octa data.parquet

The same applies to any minimal container or a bare window manager with no portal installed.

Opening files¶

No reader available¶

The error reads "no reader available for FILE", meaning Octa doesn't recognise the extension. Things to try:

Check the extension spelling. .parquet, not .parq. .csv, not .csv.txt.
Use File → Open as... and pick the format the file really is. This is the one to reach for when the extension lies about the content, such as a .log that actually holds JSON. The file picker there shows every file, not just the recognised ones, and you can pick several at once. If the file is already open, View → Reopen as does the same thing in place.
Add the extension to Settings → Files → Open as text to make Octa always treat that extension as plain text, for log / config files you open often.
As a last resort, force text: rename the file with a .txt extension, or open it via the Raw view (octa --schema FILE won't work but the GUI can open anything via the text-reader fallback).

When the format-specific reader errors out, Octa falls back to plain-text rendering in the Raw view. The orange banner at the top of the editor shows the parse error, which is your debugging starting point.

Common causes per format:

CSV / TSV: unusual quoting or escape that the reader can't guess. Switch the Raw view's Quote / Escape combos to match the file's actual convention.
JSON: malformed JSON. Try a JSON linter to spot the exact error position.
YAML: indentation issue or tab character in a structural position.
TOML: type-mismatched value or unrecognised key.

Opening a large file looks frozen¶

When you open a single-table file over 8 MB, Octa reads it, and prepares it (whitespace trim, header cleaning, numbers, and dates when switched on), on a background thread. A "Loading file..." spinner turns in the status bar and the window keeps responding meanwhile. Smaller files load at once, with no spinner.

If the window stops responding:

Before the spinner appears, the file most likely hit a reader that must load the whole file before showing anything (Excel, JSON, SPSS, Stata, or a table picked from a database file). Wait it out, or take a quick look with octa --schema huge.xlsx.
After the table appears, see the next entry.

Octa freezes or closes after a large file opened¶

The table shows, then the window stops responding, and after a while Octa disappears without a crash report. On Linux the system log (journalctl -k) shows Out of memory: Killed process ... (octa).

Cause: the loaded rows do not fit in memory. Octa holds every loaded row, and five million rows of an 18-column CSV take about 5 GB, so a raised or Unlimited row cap in Settings > Performance can ask for more than the machine has.

Fix: lower the row cap, or open the file in large-file mode, which keeps the rows on disk.

Date columns stay text¶

Octa does not look for dates when a file opens unless you switch that on, so a CSV's date columns arrive as text. That is the default because the check adds seconds per date column to opening a file of millions of rows.

Columns > Detect dates turns every column that holds only dates into dates, in the background, and one Ctrl+Z undoes it.
Change type converts one column.
Settings > File-Specific > Detect dates on load does it for every file you open, at the cost described in Big files opened the ordinary way.

Large file takes forever to open¶

Streaming readers (Parquet, CSV, TSV) cap initial-load at 2,000,000 rows (configurable under Settings → Performance → Initial-load row cap). Non-streaming formats (Excel, SQLite, JSON) load the whole file before showing anything.

Things that add to the time:

Detect dates on load: about three seconds per date column at five million rows. Off by default; Columns > Detect dates does the same later, on demand.
A raised row cap: every row loaded costs reading time and memory. A file far bigger than memory is better opened in large-file mode, which reads only what is on screen.

If you only need a quick look, the CLI is faster, since there's no GUI render path, so the cost is just the read plus a small projection:

octa --schema huge.parquet           # streams up to the initial-load cap, projects schema
octa --head huge.csv -n 10           # streams up to the cap, then truncates to N

For non-streaming formats (Excel, JSON, SPSS, Stata) the whole file still loads to populate the table, so octa --schema and --head on those formats aren't materially faster than the GUI's load step.

Valid JSON still fails to parse¶

The error reads "Failed to parse as JSON" even though the file is syntactically valid JSON. Octa's reader expects either:

A top-level array of objects (each object becomes a row).
A top-level object with array-typed values (parallel arrays become rows).

If your top-level JSON is a single non-array object, Octa wraps it in a one-row table; that usually works but can surprise. Files with nested objects deeper than 2 levels get stringified into Nested cells; expand them via the JSON tree view.

The GUI feels slow¶

The window stops responding on a very large table¶

With millions of rows loaded, one thing still runs on the thread that draws the window: saving to SQLite, DuckDB or GeoPackage. These change the file in place and need the live table, so the window waits until they are written. Every other save runs in the background; see Saving a big table.

The SQL panel no longer belongs here: copying the rows (yours and the other open tabs'), attaching a database and running a query all happen in the background.

A feature does nothing in large-file mode¶

Large-file mode keeps the rows on disk and holds one page of 2,000 rows. Editing is off, and analyses cover only the page on screen. Search, Column Filter, Filter by value, the Ask box, sorting by a column, the SQL panel's data and Save As work on the whole file. The comparison table lists every difference, and how to reach every row anyway.

Scrolling stutters during background load¶

The background loader is filling rows. Watch the status bar: the busy spinner runs while rows are streaming in. Once bg_loading_done flips, scrolling smooths out.

For files over a few GB, raising Settings → Performance → Initial-load row cap uses more memory but eliminates the background-load lag on initial scroll.

Raw view feels laggy¶

Syntect tokenisation is doing real work per keystroke in the Raw view. Three options:

Reduce Settings → Performance → Syntax-highlight size cap (set to 0 for fully plain monospace).
Switch the file off the Raw view (cycle with the CycleViewMode shortcut, F4 by default, if applicable).
For huge CSV/TSV files in Raw view, accept the one-shot prompt that asks to disable column alignment + coloring for that tab.

High RAM use¶

The biggest consumers:

Initial-load row cap: 2M rows of a wide table can be gigabytes; five million rows of an 18-column CSV took 5 GB.
Background row buffer for streaming loads: temporary, but large during the load.
Image previews (EPUB): uploaded textures stay in memory until the tab closes.
Compare view: both sides loaded fully into memory.

Close unused tabs (or reopen with the lower cap) to free memory.

Saving fails¶

Database save: schema mismatch¶

You renamed, added, or removed a column. Database saves reject schema changes by design (see Saving → Databases): the in-memory column set must match the on-disk schema.

To do a schema change:

Make the change in another tool (sqlite3 CLI, DBeaver, etc.):

ALTER TABLE users ADD COLUMN signup_source TEXT;

Reopen the database in Octa; the new schema is now the baseline.
Edit and save.

Format does not support writing¶

The error reads "format X does not support writing", meaning you're trying to Save as into a read-only format (SAS, RDS, HDF5, NetCDF, EPUB, GeoJSON). Pick a writable format instead (CSV, Parquet, JSON, SQLite, etc.). The supported-formats matrix lists which formats round-trip through write.

CSV save lost my dates¶

Columns turned into dates (by Detect dates on load, Columns > Detect dates or Change type) write back as canonical ISO YYYY-MM-DD on text outputs (CSV / JSON / etc.), regardless of the source format. With both date switches at their default (off), a CSV's dates stay text and are saved exactly as they were. If you want to preserve the on-disk format (e.g. DD.MM.YYYY) after a conversion:

Converted on load: click Dismiss on the date-format-change banner. Converted by Detect dates or Change type: press Ctrl+Z. Either puts the column back as its source text.
Save. The original strings are written back unchanged.

See Date Inference for the full mechanics.

Tabs / open files¶

Closed a tab by accident¶

Ctrl+Shift+T (the ReopenLastClosedTab shortcut) reopens the most recently closed tab.

Tabs disappear after restart¶

Octa doesn't persist open tabs across sessions yet. Workaround: re-open them from File → Recent files (the entry count is configurable in Settings → Files).

File → Close directory hides the folder sidebar without closing any tabs. Then File → Open directory… to point at a different folder.

Keyboard shortcuts not working¶

A shortcut does nothing¶

Common causes:

A text editor is focused (Raw view, SQL editor, search box, rename dialog). Most table-level shortcuts gate on "no TextEdit focused" so the keystroke can reach the editor. Click outside the editor and try again.
Read-only mode is on (F8 toggle). Many editing shortcuts no-op while read-only.
The action is rebound or unbound. Check Settings → Shortcuts or the full keyboard shortcuts reference.

Two actions claim the same combo¶

The Settings dialog flags conflicts when you record a binding. If two actions slipped through with the same combo somehow, the Settings → Shortcuts grid highlights both rows; fix one and Apply.

Assistant (chat)¶

Ollama: "no user query found in messages"¶

A turn fails with:

Error: ollama: HTTP 500: no user query found in messages

Ollama sizes its context window from the machine's VRAM, which is 4k tokens on a modest box, and Octa's first request already carries about 6.5k tokens of tool definitions. When the conversation does not fit, Ollama drops the oldest messages, and in a round that has run a tool (system, your question, the tool call, the tool's output) the oldest one is your question. Models with a built-in prompt renderer, such as Qwen 3.8, then refuse the prompt with the message above; other models answer a question they can no longer see, which is harder to notice.

Octa requests a 32k window explicitly on every turn, so this is fixed from 0.19.3 onwards. On an older build, raise the server's default instead:

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

If you run Ollama as a service, put it in the unit's environment (systemctl edit ollama) rather than in your shell.

Ollama: "timeout: receive response"¶

A Data-mode turn, Explain this file typically, fails after about two minutes with:

Error: ollama: request failed: timeout: receive response

Ollama sends nothing, not even the HTTP response headers, until it has loaded the model and read the whole prompt. A first Data-mode request carries several thousand tokens of tool definitions and file context, and on a CPU, or a model that only partly fits the GPU, reading them takes longer than the two minutes Octa allows a hosted API to start answering.

From 0.19.3 an Ollama turn gets thirty minutes to start, and the spinner shows a clock while it waits. On an older build, use Just answer for questions that need no data, or a smaller model.

Updates¶

Update check failed¶

Octa checks GitHub releases via HTTPS. Common blockers:

No internet (or firewall blocking github.com).
Corporate proxy. Octa doesn't yet honor HTTPS_PROXY env vars; this is a known limitation.
Rate-limiting from the GitHub API (very rare for individual users).

You can always download the latest binary manually from the releases page and swap in place.

Linux: update needs elevation¶

The update dialog reports "Needs elevation to install", meaning Octa was installed to a system directory (/usr/local/bin/octa) but the auto-updater can't write there as your user. Two options:

Re-install to a user-local prefix: ./install.sh ~/.local.
Run the update step with sudo.

The dialog explains and links to both paths.

Copying an error message¶

Error text in Octa is selectable, and right-clicking it offers Copy. That covers the message under the toolbar, the Test connection and Sign in results in Settings, and the failures a save or a connection reports. Failures stay on screen for a minute rather than the ten seconds a confirmation gets, so there is time to read one and copy it.

Paste it straight into an issue: the text usually carries the whole reason, including the HTTP status a server replied with.

Still stuck?¶

For MCP server issues see the dedicated MCP troubleshooting page.
For bugs (Octa behaving differently than this page describes), open an issue at github.com/thorstenfoltz/octa/issues. Include your Octa version (octa --version), OS, and exact reproduction steps.
For feature requests or general questions, the Discussions tab is the right place.