Troubleshooting and FAQ
The messages you are most likely to meet, what causes each, the limits a module runs within, and questions about the Python console.
Install and pack errors#
Shown in the Extensions status line, by the builder's Export, and by ckext pack and
ckext test. Nothing is installed.
| Message | Cause and fix |
|---|---|
This module is for CivilKit Studio: its contribution points (design-check) are not among this app's (buckling.tool) | A Studio module. Its capabilities are Studio's, so it cannot run here. A Buckling module contributes {"point": "buckling.tool", …}. |
manifest.json missing required field: civilkitApi | One of id, name, version, civilkitApi, contributes is missing. See manifest.json. |
manifest.version is not a valid semver | Use 1.0.0, not 1 or v1. |
manifest.civilkitApi 2.0 is incompatible with host 1.0.0 | Use "^1.0". |
Bundle missing manifest.json, Failed to unzip bundle: … | Not a .ckext, or zipped from outside the folder so the paths have a folder prefix. Zip from inside the folder, or use ckext pack. |
The worked examples are not valid JSON: … | The builder's Export found a JSON slip on the worked examples tab; the message gives the position. |
Installed … (Community). Worked example ‹id›: ‹diff› | Installed, but the named example did not reproduce its numbers. Run Test in the builder, or ckext test, to see every diff. |
Errors while a module runs#
Shown in the module's error box (after the module's name), in the builder's preview with the line marked when it is a
Python error, as a worked example's diff, and as error: in ckext test.
| Message | Cause and fix |
|---|---|
Capability 'signature' not declared in the module manifest | Add it to capabilities (the builder's manifest checklist). See declaring. |
Capability 'getSectionProps' not granted | Declared, but Buckling has no such capability (here, a Studio one). The capability reference has the list. |
NameError: name 'O' isn't defined (and other Python errors) | A bug in main.py, at the line the traceback or the builder's mark names. MicroPython words some messages differently from CPython. |
SyntaxError: invalid syntax | Python could not read the file; the marked line is where it gave up, which may be just after the mistake (a missing colon or bracket). |
fy must be a positive finite number | firstYield was called without a positive fy. A blank form field arrives as ""; fall back to getModel()["fy"]. |
a length is not a positive finite number | signature got a zero, negative or missing length, or modes no length. |
undefined is not iterable (cannot read property Symbol(Symbol.iterator)) | signature was called without lengths. They are required. |
unknown boundary condition "s-s" | End conditions are S-S, C-C, S-C, C-F, C-G, in capitals. |
Cannot read properties of undefined (reading 'flat') | A model passed to a capability has no springs or constraints list. Add "springs": [], "constraints": [], or build it from a copy of getModel(). |
a model needs mats, nodes and elems | No model at all: a worked example without a model whose module reads one, or a model missing a list. |
element 1 refers to node 100, which does not exist | Element node indices are 0-based and must be below the number of nodes. |
element 1 has thickness 0 | Every element needs t above zero. |
element 3 uses material 2, which is not defined | An element's mat must be the id of a material in mats. |
the model has 6000 nodes; the limit is 5000 | Mesh less finely. |
Expected property name or '}' in JSON at position 1 … | A capability got text that is not JSON. Pass json.dumps(dict), not a string you built. |
The module stopped responding and was stopped. | A call took more than 20 seconds: an endless loop, or too many solves. The sandbox restarts; the next Run starts the module afresh. Solve fewer lengths or fewer variants per run. |
Limits#
| Limit | Value |
|---|---|
| Time per call (opening, each run, each worked example at install) | 20 seconds |
| Nodes in a model a capability will take, or a proposal | 5000 |
| Python heap (MicroPython) | 16 MB |
| Network, storage, page access | none (see the sandbox) |
| Contribution points | buckling.tool only |
As a guide to time: a signature curve of the default lipped C at 50 lengths, with a modes call at each
minimum, takes well under a second on a laptop; the Thickness study's 15 steps are its upper bound for that reason.
Questions#
Why doesn't try / except catch a capability error?#
In this version an error raised by the host (an undeclared call, an invalid model, an engine refusal) ends the call
outright, and Python's exception handling does not see it. Check arguments before calling, as the reference modules do,
and raise a ValueError with a clear sentence yourself.
Where does print or civilkit.log output go?#
To ckext test, as stdout: and log: lines. The app does not show it in this
version. Debug with the command line, or temporarily return what you want to see as a result row.
Which Python modules can I import?#
json and math, and the rest of MicroPython's small built-in set. There is no
numpy, no typing, no dataclasses, no file system and no network (the
console's full Python is not available to extensions). Use
"%.4g" % v formatting; f-strings work, but keep them simple. Integer division with / gives a
float, as in Python 3.
What units?#
N, mm and MPa everywhere: coordinates and lengths in mm, stresses and moduli in MPa, P in N, moments in N·mm, the bimoment in N·mm², areas in mm², I and J in mm⁴, Cw in mm⁶. Convert for display (kN, kN·m) in your own rows, and say so in the unit.
My module reads getResults, but its worked example sees nothing.#
By design: a worked example's fixture is never solved, so hasResults() is False. Either make
the example test the no-results path, or solve the curve yourself with signature, which works in examples
and makes the module independent of the app's load case.
I forked a module and installing it replaced nothing. Where is it?#
A fork has its own id (…-fork) and name (… (fork)), so it installs beside the original.
Both appear under Installed.
My installed modules or my draft disappeared.#
They live in this browser's storage for this site. Clearing site data, a private window, or another browser or device
starts empty. Keep the .ckext files; reinstall them from a file.
Can I use one module in both Buckling and Studio?#
Not as it is: the two apps offer different capabilities and contribution points, and each refuses the other's modules. The format, the UI tree and the worked-example rules are the same, so most of a module's structure carries over; the engine calls do not.
Is a Verified module safe to use for design?#
Verified means its worked examples reproduce their cited numbers. It is a test gate, not a review: someone still has
to check that the examples are the right ones, that the clauses are current, and that the module applies to your
section. Read its source lines and its README.
The Python console#
Why does a typo ask me to download full Python?#
Before running a script the console compiles it on MicroPython. A SyntaxError there usually means syntax
MicroPython does not have (some f-string forms, match), which full Python does, so the console offers to
run it there (the compile check). It cannot tell that from a typo: a missing
bracket or colon is a SyntaxError too. Choose Not now: the console shows
MicroPython's error, with the line marked. Fix it and run again. Once full Python is on the device it is not asked
for again, and full Python reports the typo itself.
Why is my numpy script asking to download?#
numpy is not part of MicroPython, which the console runs first. A script that imports numpy, scipy, matplotlib or
another module MicroPython lacks needs full Python (Pyodide): 12.9 MB for Python, 2.8 MB for numpy, more for
matplotlib (9.8 MB) or scipy (13.4 MB). The console downloads it only when you agree, once: it is kept on the device and
works offline after that. Tick Always load it on this device without asking to skip the
question. To avoid the download, write the script without numpy: cufsm_rs itself works on MicroPython
(one-way compatibility).
Where do my scripts go?#
Nowhere but this browser. A script runs in a background worker on your device; there is no server, and nothing is
uploaded. The editor's text is kept as a draft in this browser's storage for this site, one per browser and device: a
private window, another browser or clearing the site's data starts afresh. Use Download to keep
a script as a .py file, and Open… to bring it back
(drafts and files).
Why do numbers differ in the last digits between runtimes?#
Between the console's two Pythons, the numbers are the same; their printing is not. Both call the same engine and
numbers cross bit for bit, but MicroPython's float formatting is not correctly rounded, so print(x) can
show a different last digit from full Python's. Format what you print ("%.6g" % x) and the two nearly always agree.
Against pip install cufsm-rs-py on your own machine the results themselves can differ slightly: the browser
engine and the native one use different maths libraries for sine, cosine and arctangent, and where a problem is
ill-conditioned (very long half-wavelengths, the classification of an unsymmetric section) a last-bit difference grows.
The same numbers gives the sizes.
Can a shared extension use numpy?#
No. Extensions stay on MicroPython, in their sandbox, with no network, storage or page access, and only the
capabilities they declare. Full Python in the console can import js and reach the page, which is fine for
your own script and not for a module someone else published. Put numpy work in a console script, or write the module
with loops; its engine numbers come from capabilities either way.
My script has no numpy, but it ran on full Python.#
It used something MicroPython lacks partway through: a built-in, a module function, a keyword such as
json.dumps(x, indent=2), or numpy-style use of a result (r.curve * 2,
a[i, j]). The line under the badge says which line stopped MicroPython and why
(the runtime fallback). Change that line and it runs on MicroPython again.