Diagnose the failing layer
Start with the smallest direct check. A source problem, provider problem, and interpretation problem need different fixes.A file does not load
- Run
/filesand read the skipped-source reason. - Confirm the extension is supported. Word documents, images, email files, HTML, XML, and OpenDocument files are not current inputs.
- Confirm the path is not hidden and is within eight levels of the opened folder.
- Check that
.fellaignoredoes not match its name or workspace-relative prefix. Patterns are not globs. - Confirm Fella can read the file and that another program is not locking it.
- For
.parquetor.pq, use a custom DuckDB build or convert the file to CSV/JSON. Release builds do not include Parquet.
fella.md at the workspace root is intentionally omitted from /files; it is prompt context.
The table loaded incorrectly
Run:Fella cannot reach the model
Use/auth to inspect login state, /login <provider> to replace the key,
and /model to refresh current model IDs. Provider catalogs and IDs can change
independently of Fella.
HTTP 429 and transient server failures may be retried, but quota, billing, privacy settings, unsupported tool calling, or an unstable endpoint still require provider-side action.
An answer is plausible but wrong
Open How this was analyzed and check, in order:- Correct files and tables.
- Correct date range, units, category spelling, and status filters.
- Correct join keys and join type.
- Correct aggregation and denominator.
- Rows that actually support the prose.
- Verification warnings.
/sql. A green check is not a semantic correctness guarantee.
There are no analysis details
Fella can answer general or conversational questions without a tool call. In that case there is no recorded workspace analysis or source evidence to inspect. Ask a source-bound question such as “Usingtransactions.csv, calculate…” or request the relevant file/table explicitly.
Python fails or feels unsafe
run_python is built into Fella. It supplies median, stdev, Pearson
correlation, and simple linear regression helpers, plus sql(query), which
returns a list of dictionaries from the mounted workspace. It does not need a
Python installation or third-party packages.
Python runs without a confirmation prompt inside an embedded RustPython/WASM
guest. The guest has no filesystem, network, environment, or subprocess access;
the host provides only captured output and bounded read-only SQL. Fuel, memory,
stack, source, output, row, and response limits apply. The model should choose
the read-only route that best preserves the question’s meaning: SQL for
relational queries, Python for statistical calculations, and file search or
reading for narrative sources. Clear evidence matters, but do not force every
analysis through one language or tool sequence.
A PDF cannot be searched
Fella extracts an existing text layer and does not perform OCR. If selecting text in a PDF viewer does not produce meaningful text, OCR or convert the document first. Password-protected, malformed, or image-only PDFs may be skipped or produce poor extraction.The experimental MCP command
/mcp is retained as an inert signpost. It does not connect to a service,
store connector credentials, or add tools in the personal release. A custom
fork that implements a connector owns its network, credential, and permission
review.
The desktop window does not open
Use the installer built for your operating system and architecture. On Linux, Electron requires the system’s Chromium runtime libraries; install missing shared-library packages reported by your distribution before retrying. For development, runpnpm electron:dev from the repository root. If it reports
that port 1420 is already in use, stop the other Vite/dev session before
starting another one.
Next steps
Check known limits
Confirm whether the behavior is outside Fella’s current scope.
Report a reproducible bug
Include the OS, steps, expected result, actual result, and safe sample data.