Troubleshooting
CableDyn is designed to fail closed with a clear message rather than return a quiet wrong answer. This page maps the messages you will actually see — a rejected deck, a solve that will not converge, a combination outside the coupled boundary of OpenFAST (maintained by NLR, the National Laboratory of the Rockies, formerly NREL) — to the reason and the supported path forward. Questions about results and settings are answered in Frequently asked questions.
Exit codes at a glance
Code |
Meaning |
First thing to check |
|---|---|---|
|
completed; the completion line
|
— |
|
the run was refused or its input could not be used: unknown option, wrong argument count, empty or over-long argument, output root equal to the deck, unwritable output directory, unreadable or unparseable deck or auxiliary file, out-of-range value, unsupported feature, or an output file that cannot be opened during the run |
the stderr message names the file, line, keyword, or feature — see below |
|
an |
geometry, mesh, time step, and continuation — see Non-convergence;
for the plausibility guard, reduce |
The complete stream and exit-code contract is in Standalone Windows driver. Error messages are on
stderr. If you redirected it away (2>/dev/null), rerun without the redirect.
A run that stops before TMax with no error message and without the closing line
CableDyn_driver: ended with exit code <n> was ended from outside the driver, for example by
taskkill /F (which leaves exit code 1) or End task; taskkill /IM CableDyn_driver.exe
ends every CableDyn run on the computer at once. An interrupt or a fatal fault is reported on
stderr with the simulated time reached. See When a run ends early.
Reading an error message
A row-level parse error names the file and line and quotes the offending row:
CableDyn_DeckDriver: deck line 42: column 3 value "500/2" contains "/", ",", ";" or a repeat count "n*"; ... [row: 1 chain 500/2 ...]
Auxiliary files use their own label in place of deck (for example motionFile line 7 or
bathymetry file line 3). Validation errors that are not tied to one row name the object
instead: a duplicate or undefined id is quoted in the message (duplicate POINT id 4,
LINE 2 references undefined POINT id 9).
A solver failure message is not cut off by a fixed-size buffer: it can run to several hundred characters (the tensile qualification failure of a dynamic step names the element, the force, its limit, and the remedy), the driver prints it whole, and the C API retains up to 4096 characters per handle.
A deck is rejected (exit 1)
Fail-closed at parse is a feature: it means the deck named something CableDyn will not silently reinterpret. The tables below are grouped by message class.
Command line and files
Message |
Cause and fix |
|---|---|
|
only |
usage printed on stderr, no other message |
the driver needs exactly two arguments: |
|
shorten the path (run from the case directory and use relative paths) or supply the missing argument. |
|
the output root is the deck’s own stem, so |
|
the output directory does not exist or is not writable. Create it first; the driver does not create directories. |
|
only a driver built from source with the GNU toolchain gives this: the name is outside
the system code page and the volume has no 8.3 short name for it. Use the release
|
a file in a folder with accented or non-Latin characters is not found, with an older or self-built executable |
the release executables run with UTF-8 as their Windows code page and open such folders
(Windows 10 version 1903 or later). An executable built without
|
|
a referenced file is missing or unreadable. Paths inside a deck are resolved relative to
the deck’s directory (the OWC table relative to the Syrope settings file), not to the
terminal’s current directory. A |
|
an output file became unwritable after the start-up check (for example, it is open and locked in another program). Close it and rerun. |
Records, tokens, and sections
Message |
Cause and fix |
|---|---|
|
a table value that is not one plain number. CableDyn never reads |
|
a record whose text outside a |
|
a record containing |
|
a row with the wrong number of columns. A stray comment without |
|
a LINES attachment is neither a point id nor a rod end. Rod ends can be named directly
( |
|
shorten the channel; valid channel names are far shorter than the limit. |
|
a typo in an |
|
text after the terminal |
|
use one of the spellings listed in OPTIONS reference and defaults ( |
|
CableDyn always solves the static equilibrium directly; delete the |
a channel like |
an |
Clock, motion, and environment
Message |
Cause and fix |
|---|---|
|
the standalone driver needs both or neither. Add the missing one. |
|
choose |
|
these features act only in a dynamic march. Add |
|
waves need a flat depth; a |
|
these routes have no seabed friction. Remove |
|
a deck that mixes |
motionFile |
every row time must be |
|
the file is missing at least one (point, time) pair. Every prescribed point needs a row at
every grid time, including |
motionFile |
a row has fewer than eleven plain numbers, or a header line is not commented. Comment
header lines with |
motionFile |
the |
|
these routes hold their coupled endpoints. Remove |
|
the |
|
keep one seabed definition. |
|
the wave trough is at or below the seabed ( |
|
|
|
an elevation-history file cannot drive a coupled run or a mixed standalone deck. Put the sea state in SeaState (coupled) or use a single-family standalone deck. |
|
|
|
keep either the |
a WaterKin wave/current combination is rejected |
the requested host and file sources cannot be separated by the nodewise fluid sampler without double counting. Use independent sources that Capabilities and route selection lists, or move the complete environment into OpenFAST SeaState. |
Model data
Message |
Cause and fix |
|---|---|
|
a |
|
End A is the fairlead/upper end. A stock anchor-first row ( |
|
in a deck without dynamic points every line runs from a fairlead to an anchor. A line
between two Coupled points (a shared line) is supported only between two |
|
a deck with |
|
a mixed-topology deck that has |
|
the standalone driver runs a mixed |
|
the shared mooring of a FAST.Farm farm runs in still water (no fluid field spans the
farm). Remove the |
|
a Fixed anchor within |
|
a single-family finite-EI deck is solved by the dynamic finite-EI workflow. Add
|
|
an |
|
the net-buoyant rejection above (dry mass ≤ displaced mass, unchanged) of an |
|
|
|
write |
|
a Syrope line is one |
|
see the Syrope column rules in Deck format reference (.dat): |
|
the |
|
a |
|
a |
|
each standalone route owns one object family. Split the model or use the combinations listed in Capabilities and route selection. |
|
remove the duplicate rod-end POINT row (the end points are created automatically when a
line names the rod end), supply |
|
|
|
bending end connections apply only to |
|
remove |
Torsion
Message |
Cause and fix |
|---|---|
|
a torsion row is |
|
give |
|
the static twist is ramped in stages of at most 45°, so it is limited to 1000 turns; check
the units of |
|
torsion has no |
|
torsion is solved on cubic-Hermite lines whose End B is an anchor. |
|
outside the torsion scope (Capabilities and route selection). Move End A to a |
|
the standalone deck that mixes |
|
linearise the model with |
|
the host turned a fairlead by more than 90° about the line’s end direction without a step (an output probe or a non-stepping input update). Keep the platform turn per coupling step well below 90°. |
|
the body turns faster than one step can follow the twist; reduce |
|
remove |
|
a |
|
the roll column drives the frame of a torsional line’s moving end, starts from 0 (put a
constant twist in |
FAILURE and CONTROL sections
Message |
Cause and fix |
|---|---|
|
write |
|
number the rows 1, 2, 3, … in deck order. |
|
every listed line must end at the failing point. |
|
a row with both triggers at zero could never fire. |
|
failures act on POINTS; name the point id ( |
|
FAILURE runs on the |
|
a FAILURE deck with Rigid6 bodies runs on the staggered body scheme, which takes the bodies and their lines only; model a clump or buoy on the line as part of a body. |
|
the standalone driver does not consume CONTROL. Line control is an OpenFAST
|
|
write |
|
the command lengthens the line’s fairlead-side segment by more than |
|
on a line of several sections the controlled segment is shorter than half of
|
|
the configuration blend has no committed-length treatment, so a ramp would lag; remove
|
A solve does not converge
An EI = 0 static line that does not converge, or a dynamic step that does not converge after
the recovery substeps, ends the run with exit code 2; the .out holds the converged prefix
for inspection only. A finite-EI static initialisation failure (finite-EI cable static solve
failed or unresolved/kinked finite-EI equilibrium) also ends the run with exit code 2.
The EI = 0 catenary path and the finite-EI static solve are both robust from a trivial seed,
but a few geometries are genuinely hard:
A large grounded touchdown on the
EI = 0path. A long, near-horizontal grounded run can make the linear-Lagrange tangent singular regardless of seed. If the case is a lazy-wave or bending-dominated cable, use the finite-EI path (EI > 0), which is built for it.A weightless finite-EI line longer than its span.
the weightless (neutrally buoyant) line is longer than its spanmeans every element has zero net weight (to a relative 1e-6 of its displaced weight, attachments included). Such a line has no catenary: with no weight a tension-only line is straight, and a longer one could only bow by bending under axial compression, which a cable does not carry. Shorten the line to its span, or give it net weight (a largerMassDenInAir, or clumps) or a tension that holds it taut. A line heavier than water with the same symptom getsthe net-heavy line is too long for its span to hang as a catenaryinstead.A finite-EI lazy-wave cable at too coarse a mesh. An under-resolved arch or touchdown carries a large element
h·κand can stall the dynamic Newton. The resolution metric flags this; the builder can auto-refine a fragile mesh when the deck opts in (adaptive_mesh True). This remains true when a large net-buoyant mesh first uses coarse-to-fine sequencing: the converged sequenced state is still diagnosed and, when necessary, warm-start refined. Otherwise increaseNumSegson the sag-bend and hang-off sections.Several separated finite-EI contact regions. These can be physical: a cable can bridge a bathymetric rise, or a buoyant section can separate two broad grounded heavy sections. CableDyn records the island count but does not reject that topology. Adaptive refinement is requested only when contact classification toggles over one interior node (an isolated contact node or isolated suspended gap), which is a mesh-scale signal; refine the local sections if that signal remains active.
A residual-converged folded branch. CableDyn checks the element rotation measure after every finite-EI sequence attempt, every final deck-built equilibrium, and the public automatic-mesh route.
max(h*kappa) > 0.7is rejected by name even if Newton’s residual is small. This is a mesh/branch safety failure, not permission to relax the tolerance. Increase resolution in the reported high-curvature section and inspect the static profile. The check samples element interiors adaptively, so a cubic-element fold cannot hide between output nodes.Odd, prime, or section-wise nonuniform meshes. These are supported; do not change
NumSegsmerely to make the total divisible by two. The nested hierarchy retains physical section interfaces and interpolates at the true cumulative rest-length coordinate. Its suspended-span bending-scale preflight checks the actual longest proposed coarse element, so a sparse long section is not over-coarsened merely because the deck also contains many short elements. Flat-bed installed lines with an already supported anchor retain their grounded-tail branch homotopy and are still accepted only after exact-mesh residual and kink checks.A very slack cable on a frictionless flat bed. If its rest length exceeds the vertical-plus- horizontal L-shaped path between the endpoints, a smooth single-touchdown equilibrium may not exist: the surplus must fold or form another contact region. CableDyn rejects a resulting element-localized wad through the curvature safety check. This is not fixed by relaxing Newton tolerances; revise the physical support/contact model or geometry.
A line resting in a trench, valley or pit of a gridded bathymetry. A frictionless grounded run’s tension \(T = T_0 + w\,(z - z_0)\) falls with depth. In a trench deep enough it reaches zero, and an
EI = 0line then rests slack at the bottom with its excess length piled there; the anchor tension of the run rising from the pile is \(w\) times the depth of the trench below the anchor, whatever the line length. On a two-dimensional rough bed the run slides sideways into the valleys. Both rest in the creases of the bilinear grid, which the solver rounds over 5 % of the grid spacing (see Theory) so that a node has an equilibrium there. A pile appears in the static profile as coincident nodes with zero tension and large turning angles; a finite-EI line carries compression there instead, which the driver notes. With 5 m elements on steep trench walls the end tensions of a pile still change by about 1 % on a mesh four times finer: refine the line over the trench when they matter.A grounded run that slides down a slope, or anchor tension with as-laid friction. By default (
staticsFriction none) the static solve is frictionless in still water, so a grounded run on a slope slides down it whateverfrictionMuis, and a line longer than its span folds or is rejected.asLaid staticsFrictionholds every grounded node toward its as-laid position (see friction in statics), so the run rests where it was laid. A line laid slack (asLaidTension 0) and pulled taut by its fairlead is then held back by friction along its grounded run, and its anchor tension is lower than the frictionless static’s by up tomu wtimes the grounded length (an 850 m chain in 200 m of water withfrictionMu 0.35: 1352 → 368 kN). If the run was laid at a known tension, give it asasLaidTension(orasLaidTension<ID>): a run laid at the tension it carries mobilises no friction.A finite-EI line laid past the point under its fairlead (
asLaid staticsFriction). A line longer than the seabed run from its anchor to the point under its fairlead plus its hang is laid beyond that point, and its suspended part turns back over the grounded run at the touchdown. On anEI = 0line this fold solves; a finite-EI line must round it into a hook of its bending length, which the static solve may not reach (it then fails with its route diagnostics, for exampletoo long for its span). Lay the line across the span (layAzimuth, e.g. 90° from the anchor → fairlead direction), shorten it, or move the anchor.A twisted finite-EI line.
torsion continuation stalled at Phi = ... (target ...)reports the imposed twist the static ramp reached: beyond it the line has no nearby static equilibrium on the path, typically because a loop is forming (hockling), which needs a dynamic analysis and is not resolved as self-contact.finite-EI torsion static solve ended on an unstable equilibriummeans the descent from a buckled (unstable) twisted state did not find a stable one.the twist moved more than pi/2 from its committed value in one stepstops a dynamic step that would change the twist by more than a quarter turn (the unwrapping of the twist cannot be trusted beyond it): reducedtMor slow the imposed roll.tangent turns by more than 120 degreesnames an element or node pair where the twist of the centreline is no longer reliable: refine the mesh there.A finite-EI equilibrium reported unstable.
found no physical equilibrium ... the converged state is an unstable equilibrium (tangent stiffness not positive definite)means the state that balanced its residual is a saddle of the potential energy: a compressed strut, a buckled arch or an inverted fold. A coarse mesh can also produce it. On elements longer than half the bending length \((EI/|w|)^{1/3}\) the axial force oscillates into compression at Gauss points near touchdown or a section change, which lowers the out-of-plane stiffness of a line solved in 3D. Each static route therefore refines such a state to a mesh that resolves the bending length before it fails: the catenary-continuation route is repeated there, and the mesh-sequenced state is prolongated and polished there. If the message names that refined mesh as well (still unstable on the refined mesh), the instability is physical: check the layout, the line length and the buoyancy.Discrete buoyancy modules.
finite-EI static solve with discrete ATTACHMENTS failed at load fraction ...means the homotopy from the smeared modules to the lumped ones (see Discrete attachments in Theory) did not reach the discrete equilibrium: the damped Newton solve of a load step did not converge, nor did its pseudo-transient and line-search repetitions, down to steps of 1/1024 of the module loads (or 64 load steps failed in all). The message names the load fraction of the first failed solve and the load fraction the homotopy reached. A discrete state reached by those repetitions or smaller steps is checked as the smeared one was;... the discrete equilibrium reached after a failed Newton solve ...names the check it failed (the kink limit away from the attachment nodes, the tensile contract, the physical-branch audit or the stability test), and a state that passes them is reported in the note... was reached after a failed Newton solve ... and passed the acceptance checks of the smeared state. Check that the deck with the modules replaced by the equivalent smeared buoyancy section solves; if it does, the discrete layout itself is the difficulty.A cold start at full load. The static solve continues the load in stages; if you have hand-tuned a case into a bad basin, remove the tuning and let the default continuation run from the catenary/arch seed.
If a dynamic step fails after a good static IC, the usual cause is a time step too large for a
transient event (a snap) — but note the implicit integrator’s whole point is large steps, so
first confirm the static IC itself is smooth (plot the <out_root>.static.out curvature).
The failure message reports the simulated interval; recovery_max_substeps raises the
internal subdivision ceiling, and dynamic_solver sets the dynamic Newton tolerance and
iteration budget (see OPTIONS reference and defaults). Qualify any change against a smaller dtM.
Warnings and notes that do not stop a run
Message |
Cause and fix |
|---|---|
|
with the other end free to twist the line carries no torque, so the torsion columns of the restrained end have no effect. Restrain both ends to solve torsion. |
|
the static twist stage of a torsional line. A non-zero descent count means the straight or
untwisted branch was unstable at the imposed twist and the solve moved to a buckled shape;
check the shape and the |
|
the SeaState grid ( |
|
the fairlead tension over the EA of the End A section exceeds |
|
a section whose segments are longer than 1/8 (12.5 %) of the line, i.e. coarser than a
uniform eight-segment line, is too coarse to follow the line shape there; a 100 m
one-segment top section of a 520 m line shifts the fairlead tension by tens of percent.
The rule compares the segment length with the whole line, so it does not depend on how
the line is split into sections. Refine its |
|
a grounded run of this type would sink deeper than its own diameter into the penalty
seabed. Raise |
|
the deck has no |
|
the lines start at rest, so an end that starts at speed sends an axial shock down the line
and can put its upper part into compression for several steps. A harmonic started at
|
|
a current, or a seabed sloping down past the anchor, has pushed the grounded run past its
anchor where no seabed friction holds it, and it folds back to it (see Theory).
The layout is a valid, stable equilibrium of the deck as written, but not the usual one.
Check the line length, the current and the seabed, and inspect
|
|
an |
|
in a current along the plane of the line the static state is a planar equilibrium that a
lateral disturbance would leave (the line is held in the plane only by the symmetry), and
no out-of-plane equilibrium was found. The state is valid in the plane; a cross-flow
component or seabed friction ( |
|
the time-step audit of a finite-EI line: above 0.25° per step (0.1° with
|
|
the time-step audit of an |
|
information: the steps in which a taut segment turned by more than |
|
information, once per run of a deck with |
|
snap loads on an |
|
a non-physical tension spike: the tension of one segment (elastic, viscoelastic or
Syrope; numbered from End A, as in |
|
printed by the standalone driver for a dynamic deck with |
|
the finite-EI deck mesh is finer than the axial-bending length \(\sqrt{EI/EA}\):
the axial stiffness of each element swamps its bending stiffness and the static
Newton system loses the precision to converge. An 80 m lazy wave (6.5 mm limit)
solves at 8 mm elements and not at 4 to 6 mm, where the solve stops within seconds
and names the mesh. Coarsen |
|
on the deck mesh, or on a refinement of it that was still too coarse, the static state read as unstable, an artefact of elements longer than half the bending length \((EI/|w|)^{1/3}\) (see Modelling workflow, step 5). The run uses the refined mesh, statics and dynamics alike, and its outputs have that many segments. Mesh the touchdown and section changes to that rule to keep the deck mesh. |
|
the deck mesh is too coarse for the bends of the static state. Either an element folded beyond \(L_0\kappa = 0.7\) (a bend shorter than the element), and the static solve refined the mesh locally where the bend is, and where elements are longer than half the bending length, at most 16-fold per deck element and graded into the neighbouring elements; or the continuation or polish failed on a deck mesh with elements longer than half the bending length \((EI/|w|)^{1/3}\), and the route was repeated on the whole line refined uniformly by a power of two, up to the factor at which every element meets that length (or, at a rotationally restrained end, on end elements halved toward the end down to its boundary layer). See Theory, Static equilibrium. The run uses the refined mesh, statics and dynamics alike, and its profile and per-line outputs have that many segments; the refinement only splits deck elements, so the node channels still name deck nodes (see Node channels on a refined line). Mesh the line to the bending-length rule to keep the deck mesh. |
|
a finite-EI line free in torsion is solved in its vertical plane, and the dynamics release
its out-of-plane DOFs. On elements longer than half the bending length the axial force at
touchdown or a section change oscillates into compression and makes that planar state
unstable out of the plane, so a lateral disturbance (a cross current, a sway motion) can
move the line from it in a way the mesh, not the physics, decides. On a line with
|
|
the element-mean axial force of a finite-EI line, averaged with its neighbours, is
compressive, and the pointwise resultant oscillates well beyond it. Refine |
curvature near a hang-off changes with |
end curvature is a boundary-layer quantity. Run a |
An OpenFAST CompMooring = 5 run fails at init
The module covers the scoped MoorDyn-F coupled surface and fails closed outside it. If init aborts with a CableDyn fatal error, check whether the deck uses one of these combinations:
Not supported on the coupled route |
Use instead |
|---|---|
active ServoDyn control ( |
line control of |
deck |
put the sea state and current in SeaState, or a current table in a WaterKin file
( |
a finite-EI cable in the same deck as Rigid6 bodies, rods, or |
model the cable and the body/point system in separate decks or use the supported combinations in Capabilities and route selection |
OpenFAST linearisation with a platform-relative cable |
linearise a pinned-hang-off, uncontrolled variant of the deck; time-domain runs support both |
a |
drive the platform through intermediate orientations |
VIV ( |
use a solver with a separately validated VIV model |
a host/file fluid combination named as inseparable |
select host wave/current and file wave/current independently as documented, or place the whole field in SeaState |
a |
represent the restoring physics with supported line/body terms or use stock MoorDyn |
Finite-EI rotational end coupling is supported in the time domain on the coupled route: an
END CONNECTIONS direction at a coupled hang-off rotates with the OpenFAST platform
orientation, the mesh angular velocity and acceleration enter the implicit residual, and the
connection moment is returned to OpenFAST on the load mesh (see OpenFAST with CompMooring = 5). In the
standalone driver an end-connection direction stays fixed in global axes on a Fixed or
Coupled point driven by a motionFile, and turns with the vessel under vesselMotion
or vesselRAO.
Everything CableDyn does support end-to-end — coupled time-domain analysis, PtfmInit,
NumCrctn > 0, SeaState kinematics, checkpoint-restart, linearisation, rigid bodies/rods, and
Mod_SharedMooring = 5 — is listed in Capabilities and route selection.
The standalone binary will not launch (Windows)
Use the release CableDyn_driver.exe or CableDyn-enabled openfast.exe. Those two
non-OpenMP x64 files are statically linked and require no adjacent compiler, BLAS, OpenMP,
or C/C++ runtime DLL. A locally built GNU/OpenMP executable may still require its selected
toolchain libraries. A GNU build loads openblas.dll from its own directory when it starts;
if the library is missing, the driver stops with exit status 2 and a message naming the
library, each location tried, and the Windows load error. Keep openblas.dll next to the
executable (cmake --install stages it) or run from the activated environment. A missing
DISCON.dll is different: the OpenFAST model explicitly
requested a ServoDyn controller, so copy that model-specific controller with the model or
disable it. See Installation (standalone binaries).
Stack size of a GNU build. A build with gfortran on Windows (MinGW-w64) links the driver
and the test programs with a 64 MiB stack reserve instead of the 2 MiB MinGW default, because
with OpenMP gfortran places fixed-size local arrays on the stack. A reserve is address space,
not committed memory. The shared library does not rely on it: a program that loads
libcabledyn, such as python.exe, chooses the stack of the threads that call it. The
stack tests check that the library runs on threads with a 1 MiB stack, and that a driver
linked with a 1 MiB reserve runs a 2048-element deck.
If your issue is not here, see Frequently asked questions; the Deck format reference (.dat) row for the feature is the authoritative statement of what is supported, and CableDyn verification and validation records exactly which cases are validated.