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 --help lists the commands; samplekit set --help explains one, with examples; -h gives 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

compute --write

formula changed

the model's formula was edited since

compute --write

never computed

the model declares it, and it was never computed

compute --write

edited

typed over its formula

keep it, or compute --force --write

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: --write answers 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.