When something goes wrong¶
This page is for when a command did not do what you expected: it refused, warned, or showed a value you did not trust. Find the symptom below; each says what SampleKit is telling you, what to do, and where the reason is explained.
SampleKit's rule is to refuse rather than guess. A misspelt name, a condition that does not read, a file it cannot read, a value it cannot vouch for: each is said, by name, never filled in quietly. The message usually holds the fix.
Getting help¶
samplekit --helplists the commands;samplekit set --helpexplains one, with examples;-hgives a shorter summary.In the terminal interface,
?lists the keys of the screen you are on.The command line and the TUI's keys list everything, generated from the version you run.
Every command's exit code says how it ended: 0 done, 1 a mistake in the command, 2 something wrong in the data, 3 the system refused (exit codes).
A name is refused¶
unknown field 'tensile_strenght', no profile named …: the message names
the nearest name that exists, and in a terminal asks whether to use it. Check
the names a project uses with samplekit list fields, and list queries,
profiles, exports, figures, scripts for the rest. A name holds
letters, digits and _, never a hyphen: gauge_length, not gauge-length.
A filter is refused¶
The message points at the character where it stopped reading: material = steel wants ==. Quote the whole filter for the shell, -f 'elongation > 20'. A text compared with a number, grade > 3, is refused where every
sample holds text (find and select samples, every
form).
A file was not read¶
warning: samples/broken.md was not read: malformed frontmatter: did not find expected ',' or ']' at line 5 column 1, while parsing a flow sequence at line 4 column 7
A file that looks like a sample and cannot be read is never skipped in
silence: the command names it, reads the rest, and exits with code 2.
samplekit list skipped lists every file set aside, and why. Open the file
at the line named: a bracket not closed, a tab, a quote. A link written
without its quotes, reference: [[steel-02]] or report: [report](r.pdf),
is refused at its line, with the quoted form to write instead,
reference: "[[steel-02]]". A Markdown file
without the --- lines at its top is not a sample at all: no command warns of
it, as of a README, and list skipped names it with its reason (a collection).
No sample is found¶
no sample here, followed by the folders below that hold samples: outside a
project, a folder is read alone, without the folders below it. Name the
folder that holds the samples, or make the folder a project with samplekit init, whose folders are all read (which folders a command
reads).
validate reports a defect¶
validate names the file and what is wrong: two units in one column, a
value outside the range the project declares, a text where a number belongs,
a pattern of [collection] files that cannot work, a link to a sample or a
file that does not exist (links). It changes nothing; fix
the file with set or an editor, and run it again (checking
them). A defect makes it exit with code 2, which
stops a continuous integration job (check a project in continuous
integration).
A value is not current¶
samplekit status lists every value that is not current, with the reason:
State |
Means |
Do |
|---|---|---|
outdated |
an input changed since it was computed |
|
formula changed |
the model's formula was edited since |
|
never computed |
the model declares it, and it was never computed |
|
edited |
typed over its formula |
keep it, or |
waits for … |
an input nobody entered |
enter the input; nothing is wrong |
failed |
its formula raised an error |
read the error, fix the formula or the data |
A table marks each in its cell, ⚠ ✎ ✗ ∅, and samplekit FILE explain FIELD says, for one value, what it was computed from and why it is in its
state (current and outdated).
A formula fails¶
compute shows the error with the formula's Python traceback, and computes
the rest. The value is marked failed, and its old number is never shown as
current. explain gives the error again. A formula that returned nothing,
a return forgotten, is said so (when a formula cannot
run).
The model does not run¶
error: the model cannot run: [model] python names nothing that exists
The model runs only in the Python environment [model] python names in
.samplekitrc, with SampleKit's package installed in it at the version of
the command line. The message names what is missing, and the command that
makes it: python -m venv .venv, then .venv/bin/pip install samplekit==VERSION; or samplekit init, which offers it. A model that
imports a package you use, numpy or scipy, needs it installed in that same
environment (where the model
runs).
Reading, filtering, validate and the exports of tables never need Python:
only computing, scripts and figures do, a figure's export among them.
validate still checks that the environment exists, and reports it missing
as a defect.
A script stops at a question¶
A script that asks with input() reads the answer from the terminal. Run
where nothing can answer, in a pipe or a scheduled job, it stops, naming the
question: give the script its value with --set NAME=VALUE instead, an
option the script declares (run a script).
A figure does not open¶
A figure opens in a window only where there is a display, and with a window
toolkit, tkinter or Qt, in the project's environment; plot says which is
missing. -o curves.pdf --write writes it to a file instead, which needs
neither.
A write is refused¶
changed since it was read: someone, an editor or another command, changed the file between the preview and the write. Nothing is written; run the command again.
read-only: the file cannot be written by you.
A question answered
n, or no answer from a script, writes nothing and exits 0:--writeanswers yes beforehand.
A copy appears beside a sample¶
A synchronised folder that met two changes to one file at once keeps the
other version beside it, steel-01.sync-conflict-….md or steel-01 (conflicted copy …).md: SampleKit leaves it out of every command and says
so. Compare the two, keep one, and remove the other (share a
project).
A change must be taken back¶
samplekit restore takes the last change back, previewed first;
restore --at puts files back as they were at a change or on a day, and
--at on any command reads the project as it was then (the
history).
Common mistakes, by subject¶
Each concept page ends with the mistakes it prevents: samples and files, values and uncertainty, readings, models, current and outdated, the history, projects.