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 the working fold 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 is no working fold
Fella can answer general or conversational questions without a tool call. No call means no workspace evidence. 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. If a calculation can be
written clearly in SQL, prefer SQL because its evidence is easier to inspect.
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 Linux window renders incorrectly
On WSLg, if the window opens but layout or compositing is broken, try: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.