Error Reference
Every fallible operation in linaldb errors loudly rather than returning a wrong or silent result: see Architecture. This page groups the errors you’re likely to actually hit.
Parse errors
Section titled “Parse errors”The engine runs a real lexer + parser first; a syntax problem produces a structured error with a byte offset and what the parser expected:
[line 1] Parse error: expected a statement keyword, found identifier `GET` (at byte 0)GET * FROM users→GETisn’t a linaldb keyword (it’sSELECT).DEFINE t AS TENSOR(2,2) VALUES [...]→ “expected[, found(”; shapes use brackets:TENSOR [2, 2].
Check the DSL Reference for correct syntax; the byte offset tells you exactly where in the line to look.
Comment-only lines (--, #, //) and blank lines are not errors: they’re recognized
before parsing and treated as a no-op.
Engine errors
Section titled “Engine errors”Occur when the syntax is valid but the operation fails at runtime:
[line 5] Engine error: Invalid operation: shape mismatch: [3] vs [4]Common ones:
| Cause | Example message | Fix |
|---|---|---|
| Referenced a tensor/dataset that doesn’t exist | Dataset not found: people |
Check spelling, or run SHOW ALL DATASETS / SHOW ALL TENSORS |
Shape mismatch (MATMUL, ADD, …) |
shape mismatch: [3] vs [4] |
Check tensor dimensions on both sides |
Singular matrix passed to INVERSE/SOLVE |
matrix is singular (not invertible) |
This is a correctness signal about your data, not something to work around |
Non-square matrix passed to TRACE/DETERMINANT/… |
TRACE requires a square matrix, got 2x3 |
Check the actual shape |
Non-symmetric matrix passed to EIGENVALUES/EIGEN |
matrix is not symmetric |
Only symmetric matrices are supported; no complex-eigenvalue support exists |
INSERT value count/names don’t match schema |
Value count mismatch: expected N, got M |
Check SHOW SCHEMA <name> |
HAVING references an unknown column/alias |
HAVING references unknown column '...' |
Check it’s actually present in the SELECT list |
| Dataset/tensor name already in use | NameAlreadyExists |
Drop/rename the existing one, or pick a different name |
Storage errors
Section titled “Storage errors”Surface through SAVE/LOAD/IMPORT/EXPORT/LIST (persistence/disk issues,
distinct from the in-memory errors above):
| Cause | Meaning |
|---|---|
Io |
Permissions issue or disk full under ./data (or your configured data_dir) |
Serialization |
Failed converting schema/stats/lineage/manifest data to or from JSON |
Parquet |
Failed reading or writing a dataset’s data.parquet |
Arrow |
Failed converting between linaldb’s row representation and Arrow’s columnar batches |
DatasetNotFound / TensorNotFound |
Tried to LOAD something that doesn’t exist on disk |
Common issues
Section titled “Common issues”“My command does nothing”: check parentheses are balanced; the CLI/REPL needs a complete statement.
A SHOW reports a dangling reference warning: one of your dataset’s columns points
to a tensor that was manually removed from the store. Fix with ATTACH <tensor> TO <dataset>.<column>, or run AUDIT DATASET <name> to check the whole dataset.
Queries feel slower than expected on a large tensor: the engine falls back to scalar execution when SIMD isn’t applicable (non-contiguous layout, or below the ~1024 element threshold). This is transparent and correct, just slower. See Architecture.