Troubleshooting — the messages you will meet and what to do#

Every message below is quoted verbatim from the source file named beside it, so you can search this page for the text on your screen. They are grouped by where you meet them — building a diagram, running it, typing in the console, exporting code, opening and saving projects — and each entry says what the text means, the likeliest cause, and what to do. The last two sections explain where messages appear (and which ones stop a run) and what to include when you report a problem.

Where messages appear, and what the levels mean#

ICoreBlocks has three channels, and knowing which one a message came from tells you what kind of problem it is:

Channel	Where you see it	What goes there
Run Diagnosis panel (left rail button `Run Diagnosis`)	one row per message, three colours: log, warning, error	everything a build, a run or a code export says about your model — `ICoreRunDiagnosis` in `src/ICoreBlocks/ICoreServices/ICoreRunDiagnosis.cpp`
Notification bubbles (title + one sentence, fade after reading; `ICoreNotificationCenter` keeps a history of them)	`Build Failed`, `Solver Terminated`, `Solver Finished`, `Project Could Not Be Opened`, `Save Failed`, `Verification Didn't Run`, …	outcomes you must act on
Main Log window (`View → Logs → Loggers → Main Log`)	plain lines with a timestamp; error lines start with `Error --` and are drawn red	the software's own log — internal faults, file I/O, project load details
Console output (`Quick Code` panel, or the terminal for a headless run)	the line's result, or `error: …`, or `unknown command: …`	console statements and recipe verbs

Two rules follow from how the run channel is wired (ICoreRunDiagnosis.cpp):

A Run Diagnosis error stops the run. logError() calls stopProjectSimulator() before the row is even shown; that is what the Solver Terminated / Simulations were aborted! bubble means. Errors are always standalone rows; logs and warnings are folded into groups (ICoreRunDiagnosisPanel.cpp).
A Run Diagnosis warning does not. The run continues; read it afterwards.

Headless (--console), the same channel prints to standard output with the prefix [ICoreRunDiagnosis], [ICoreRunDiagnosis] - Warning - or [ICoreRunDiagnosis] - Error - ; the Main Log prints to standard output and standard error.

The log file. The Main Log is written to Loggers/MainLog.log under the directory the application was started from (ICoreLogger.cpp names the relative path). It keeps the last 10 000 lines and is flushed every 5 seconds or every 50 lines (ICoreLoggerObject.cpp) — a headless run that exits in two seconds may therefore write nothing, which is what happened in every short run on this page. Two preferences govern it (the Logging section of the user preferences): Verbosity set to Errors Only drops the informational stream from the panels, the file and the console — errors are never suppressed; Write Log Files off keeps logging in the panels without touching the disk.

Messages a licence produces#

These come from the licence the application signed in with — or from having none.

Message	Meaning / cause	What to do
`Simulation is unavailable because this licence has expired. Your models still open and save — sign in again, or renew, to continue.`	the licence lapsed and the licensing service was reachable and said so	Open Account from the toolbar (or Help ▸ Account…) and sign in again, or renew. ⚠ Your work is not at risk: an expired licence is read-only, not hostile — every model still opens and still saves
`Code export is unavailable because this licence has expired. …`	the same state, met at Deploy instead of Run	as above
`Simulation is unavailable because no licence has been resolved. Your models still open and save — sign in from Help ▸ Account… to continue.` (and the same sentence for `Code export` and the other licensed capabilities)	this session has no licence at all — typically the sign-in dialog was cancelled, or you signed out	sign in from Help ▸ Account… or Account on the toolbar. Nothing is lost: models still open and save
`This licence does not include the <target> code generator. Every standard tier includes every generator, …`	a licence restricted by agreement to a subset of the generators	this is not the ordinary case — every standard tier carries every generator. Check the Account panel's tier, and the portal
`This licence does not include <feature>. The account portal shows what it covers.`	an entitlement the licence genuinely does not carry — loading blocks somebody else wrote, for instance	Account on the toolbar, or Help ▸ Account…, shows what this licence covers

⚠ Working offline is not one of these. A licence whose token has lapsed while the service could not be reached is in grace — fully functional for thirty days, with the banner counting them down. A network failure never blocks a paid user, so if you see a refusal rather than the banner, the service was reached and answered.

Building the diagram (recipe verbs and the canvas)#

Message	Meaning / cause	What to do
`unknown block type 'Nope'` (`ICoreRecipeInterpreter.cpp`)	`block(type)` was given a name that is neither a leaf name nor a full path from Block catalog — every library block	check the spelling; leaf names such as `Gain`, `Step`, `Sum` work, and so does the full `Control_Systems/Sources/Step`
`block(): a block type is required`	`block()` with no argument	give the type
`block(): 'X' cannot be created directly; use subsystem(parent?) instead`	a subsystem is not a plain block	use `s = subsystem()`
`connect(): unknown handle 'a'`	the handle was never bound in this session (handles are not saved with the project)	rebind it: `a = block(Gain)`, or `clearRecipeHandles` and start over
`connect(): operands must look like handle<index> or be a port handle, got 's.outputPort(0)'`	wrong port spelling	write `connect(s<0>, g<0>)`, or bind a port first: `p = s.outputPort(0)`
`g has no output port [3]` / `'p' is not an input port`	port index out of range, or the operands are the wrong way round	`connect(out<i>, in<j>)`: source first, destination second
`setConfig(): g has no config variable 'Nope' (editable: Sampling Time (s), Gain Value, Multiplication Type)`	the variable name is not one of that block's editable keys	copy a name from the list the message prints, or from `g.listConfig`
`setConfig(): config variable 'X' is private and cannot be edited by recipe`	that key is managed by the block itself	edit it in the block's dialog, not by recipe
`unknown block method '.nope' (methods: move, rename, resize, …)`	a typo in a verb	pick one from the list, or see the roster in Command glossary — console commands, verbs, functions
`rename(): 'X' is invalid — a name cannot be blank, start with a space, or contain any of / % ! < > ~ # $ @ ^ & * ( ) ,`	the name breaks one of those rules, or is already taken on that level	pick another
`useTemplate: an id is required — run \`templates\ `to see them` / `openTemplate: no template with id 'nope'` (`ICoreTemplateCommands.cpp`)	the template id is missing or wrong	run `templates` and copy the id; see Recipes and templates — recording, replaying and reusing diagrams
`openTemplate: 'X' was copied to … but could not be replayed — the template may have been built against an older block library`	the copy exists on disk but its recipe did not replay in full	open the copied folder's recipe file and look for the first line the Main Log reports as failed

Running a simulation#

These arrive in the Run Diagnosis panel. The row that matters is the first error — everything after it is the run shutting down.

Message	Meaning / cause	What to do
`Unable to retrieve config Gain Value at block: ICore Blocks/Home/Gain` (`ICoreBlockSolverEnvironment.cpp`)	a parameter holds text the block could not turn into the number or matrix it expects, so when the block asked for it during the build it was not there	open the block and fix the field named after `config`; every value must evaluate to a number or matrix
`Invalid sampling time for block: …` followed by `Sampling time must be a positive double`	the block's `Sampling Time (s)` is not a number	set it to a positive value, or `-1` to inherit the global rate — see Sample time and loops — how the simulator paces a diagram
`Sampling time is less than or equal to zero.` / `Invalid sampling rate found. Check software log.` (`ICoreModelSimulator.cpp`, `ICoreModelBuild.cpp`)	the global sampling time is 0 or negative, or a block's rate could not be resolved	fix `globalSamplingTime` in the model configuration (`modelConfig` prints it)
`Sampling time mismatch: block 'X' runs at … but source subsystem 'Y' runs at …` (`ICoreModelBuild.cpp`)	a subsystem chosen for export contains a block at a different rate	make every block in that subsystem run at the subsystem's rate
`Block: X has a positive sampling time, while global solver is variable-step. Block sampling time will be overridden at each step by the global variable-step.` (warning)	you set a rate on a continuous block but the solver is variable-step, so that rate is ignored (a discrete block — unit delay, discrete filter — keeps its period under variable step)	expected; switch to a fixed-step or discrete solver if you want a continuous block's rate honoured
`Joint integration produced a non-finite state at t = …`	under the default `Joint` coupling the whole diagram's continuous states diverged in one step — an explicit method on a stiff loop, or a step far too large	lower `globalSamplingTime`, or switch `steppingType` to `BE1`, `TR2` or `TRBDF2`
`Implicit step did not converge at … The last iterate is used.` (warning, once per run)	`steppingType` is `BE1` or `TR2` and the block's Newton iteration ran out of iterations at that step — a very nonlinear derivative, or a `globalSamplingTime` too large for it	lower `globalSamplingTime`; if the block is linear this should never appear, so report it
`Variable-step solver asked for a step of … below Min Step Size …` (warning, once per run)	the error controller wanted a smaller step than `minTimeStep`; the step was clamped and taken, so the tolerance is not met there	lower `minTimeStep`, or relax `relativeTolerance` / `absoluteTolerance` — see Sample time and loops — how the simulator paces a diagram
`Stop time must be higher than start time` / `Max Step Size must be higher than Min Step Size`	the model configuration is inconsistent	fix `startTime`/`stopTime` or `maxTimeStep`/`minTimeStep`
`Port signal size never converged at input port: X [1x1] against its source output port: Y [1x3]` (`ICoreModelBuild.cpp`)	the two ends of a link disagree on the signal's dimensions	check the matrix sizes of the blocks on both ends
`Port signal size diverged at port: … exceeding the … element limit. This usually means a …`	a loop keeps growing a signal (a resize feeding itself)	break the loop or fix the resizing block
`Algebraic loop detected: ICore Blocks/Home/Subtract -> ICore Blocks/Home/Gain -> ICore Blocks/Home/Subtract. Every block around this loop feeds its input straight through to its output …` (`ICoreModelBuild.cpp`; the same row refuses a code export)	a feedback loop with no block whose output is known from its state — every block on it computes its output from its input at the same instant, so there is no block to solve first	put a Unit Delay or Memory in the loop (discrete), or an Integrator or strictly proper Transfer Function (continuous), or an Algebraic Constraint block; the message lists the blocks in signal-flow order — see Sample time and loops — how the simulator paces a diagram
`Invalid matrix dimensions passed to state space. New matrices were ignored.` (`ICoreMath/ControlSystems/ICoreStateSpace.cpp`)	A, B, C, D (or a gain used as a matrix) do not multiply together	check the dimensions; a `Gain` in `Matrix (K*u)` mode needs a K whose column count equals the input's row count
`Unable to compute matrix inverse. Matrix is singular.` (`ICoreMath/Foundation/ICoreMatrix.cpp`)	an inversion inside a block met a singular matrix	see Numerics — what the solver will and will not do for what the decompositions return. (The console's `inv()` does not raise this: like MATLAB, it answers a matrix of `Inf`)
`Build failed.` + bubble `Build Failed — The model could not be built. Check the run diagnosis panel for the reason.`	one of the above happened during the build step	scroll up to the first error row
`Solver crashed: <text>` / `Unknown solver crash.`	an exception escaped a block during the run	note the text and the block you last edited; report it (below)
`Solver already running.`	you pressed Run while a run was in progress	stop it first
`Subsystem '…' is commented out. Uncomment it to run or export it.` / `Subsystem '…' lies inside the commented-out subsystem '…'. …` (`ICoreModelBuild.cpp`)	you ran or exported a subsystem that is commented out, or one inside it; a commented-out subsystem takes everything inside it out of the model	uncomment the subsystem block
My loop is one sample slower than in Simulink	not a fault, for a loop closed through a discrete delay block: the edge leaving that block carries one cycle of delay (a continuous loop under the default `Joint` coupling has none)	Sample time and loops — how the simulator paces a diagram explains why and how to compare

Note what is not an error: an unconnected input port. g = block(Gain) alone builds and runs (a real run below) and no row is raised for the missing link. If a block "does nothing", check its links before its parameters.

Typing in the console#

Full rules in The command window — the command engine for a user; here only the failures.

Message	Meaning / cause	What to do
`unknown command: foo` (`ICoreCommandResult.cpp`)	the line was not a recipe verb, not an assignment, not an expression, and not a registered command	`help` lists commands; `glossary` lists everything
`error: in [...]: the rows do not line up (1x2 above, 1x1 below …)` (`ICoreExpressionEvaluator.cpp`)	ragged rows in a bracket used as an expression. A bracket is a concatenation of expressions, so the complaint is about the concatenation, not about a literal that failed to parse	every row needs the same number of columns
`x = [1 2; 3]` succeeds and prints `x = '[1 2; 3]' # String`	in an assignment a bracket that does not evaluate falls back to being stored verbatim and typed afterwards, so a ragged one becomes a String, silently (`ICoreConsoleInterpreter.cpp`, `tryAssignment`). A bracket that DOES evaluate — including `[A, B]` and every other concatenation — is stored as its value	read the `#` type tag after every assignment; a matrix you meant to build says `# Matrix`
`error: '+' size mismatch: 1x2 vs 1x3`	matrix arithmetic on unequal shapes	`.`/`./` are element-wise, `` is the matrix product with its own rule (`'*' inner dimensions disagree`)
`error: '^' needs a scalar exponent: A^B with a matrix B is a matrix function (MATLAB's funm) the console does not have`	a matrix exponent; a square matrix to a scalar power — `A^2`, `A^0.5` — is fine	use an element-wise `.^` if that is what you meant
`error: '\' on an underdetermined system (2x3) has no single answer`	`A \ b` with more unknowns than equations: MATLAB returns a basic solution with at most `rank(A)` non-zeros, which is a different vector from the minimum-norm one	`pinv(A) * b` for the minimum-norm solution
`error: name 'q' is not defined`	a variable that does not exist in the variables space	`clearVariablesSpace` wipes them all; check the Variables panel
`error: unknown function 'foo' (or wrong argument types)`	not a matrix function, or e.g. `tf()` given a scalar where a vector is due	the function table is in Command glossary — console commands, verbs, functions
`error: '/' is only defined for matrices, scalars and transfer functions`	`/` between two values it has no rule for — a transfer function and a non-scalar matrix, for instance	divide a model by a model or a scalar; build a rational with `tf`
`setModelConfig: unknown property 'samplingTime' — run modelConfig to list them` (`ICoreModelConfigCommands.cpp`)	property names are the exact keys `modelConfig` prints	it is `globalSamplingTime`
`setModelConfig steppingType: no option matches 'Nope' — available: …`	a choice property was given text that matches none of its options	any unambiguous substring of an option works

Exporting code#

Export runs the same build as a simulation first, so everything in the running section applies. The export-specific rows (ICoreCodegen.cpp unless noted):

Message	Meaning / cause	What to do
`Invalid solver type for code export. Global solver must be fixed-step or discrete solver.` then `Code export failed!`	the model configuration is variable-step	set `steppingType` to a `Fixed-step` option, or `solverType` to discrete — see Exporting code — the ten targets, what each produces, and what verification proves
`Export to C is not supported for block: ICore Blocks/Home/X` (one per language, e.g. `ICoreCParser.cpp`)	that block has no generator for that language	the block's page on Block catalog — every library block lists its export targets; replace the block or drop the target
`Invalid target path found: …`	the target's output folder cannot be used	pick a writable folder in the target
`Invalid sampling time detected at subsystem: …`	the exported subsystem has no positive rate	give the subsystem block a sampling time
bubble `No Targets Created — Create a deploy target from deploy to hardware panel` (`ICoreCodeExportVerifierView.cpp`)	verification was asked for before any target exists	open `Deploy To Hardware` and add one
bubble `Verification Didn't Run` with `C compiler (gcc) not found.`, `rustc not found.`, `No JDK found to compile Java.`, `ghdl not found.`, `iverilog/vvp not found.`, `MATLAB not found.`, `No Python installation with numpy was found. Install numpy and try again.`, `matiec (iec2c) not found. …` (`ICoreCodeExportVerifier.cpp`)	the exported code is fine; the toolchain to run it is missing	install the tool, or give the target a custom compiler path (a target's own path overrides the scan and the app-wide default)
bubble `Verification Crashed` with `C build failed.` / `Testbench exited with code N`	the generated test bench did not compile or run	open the compiler log the target keeps; report it (below)
`Each matrix must have at least two columns (time + one signal).`	the comparison received a table with no signal column — on builds before 2026-08-17 this was also how a bailed emulation (missing toolchain, failed build) was reported; since then such a row carries the bubble's own text	if the row's reason is this text on a current build, the exported test bench ran but wrote no signal — open the compiler log; on an older build, scroll up to the `Verification Didn't Run` / `Verification Crashed` bubble that preceded it
`Code export cancelled by user after verification.` (warning)	you declined at the confirmation	nothing
bubble `Signal type not supported by <language>` with the port and the reason	a port on the exported subsystem carries a signal type that language cannot hold	pick a language that can carry it (the other targets in the queue still run), or convert the signal — see Signal types — what a port carries, and why a link is refused
`Can't edit the model while code export is running.`	an edit, an undo, or a console line arrived while a Deploy or a verification was reading the diagram	wait for the export to finish; see Exporting code — the ten targets, what each produces, and what verification proves

Opening and saving projects#

Message	Meaning / cause	What to do
bubble `Project Could Not Be Opened — This project is in a format this version cannot read. It has been left untouched on disk, and autosave is off until a project loads or you save.` (`ICoreStudioSerialization.cpp`)	the project file had content but its recipe did not replay in full — typically a project written by an older version	the file is safe: autosave is held off so the empty editor is not written over it. The Main Log names the failing line (`ICoreStudioStateMachine::replayRecipeText: unrecognized line '…'` or `… failed on line '…': <reason>`); no converter for the older format exists
bubble `Project Could Not Be Read — This project's file could not be read - it may be locked, or its permissions may have changed. …`	the file could not be opened at all	check permissions and that no other program holds it
bubble `Save Failed — The project could not be saved. The copy already on disk has been left untouched.` (`ICoreActiveProjectFolder.cpp`) / `Error — Autosave failed`	the new file could not be written or swapped in	free disk space or fix folder permissions; the previous save is intact
bubble `Already Open — X is the open project.`	you opened the project that is already open	nothing

Real runs (2026-08-17)#

Binary build-mac/ICoreBlocks.app built 2026-08-16 23:39 (approximately commit 2e126fbf). Every transcript below is the console's own output; the Qt platform noise was stripped, nothing else. Command line for each:

HOME=<scratch> QT_QPA_PLATFORM=offscreen build-mac/ICoreBlocks.app/Contents/MacOS/ICoreBlocks --console "<line>"

An unknown command, a bad matrix literal, and the same literal in an assignment

--console "foo 1 2"
Software Initialized
unknown command: foo

--console "[1 2; 3]"
Software Initialized
error: in [...]: the rows do not line up (1x2 above, 1x1 below -- every row of a bracket needs the same number of columns)

--console "x = [1 2; 3]; x"
Software Initialized
x = '[1 2; 3]'  # String

A recipe verb with a missing argument, an unknown config key, an unknown handle

--console "g = block()"
Software Initialized
block(): a block type is required

--console "g = block(Gain); g.setConfig(Nope, 3)"
Software Initialized
setConfig(): g has no config variable 'Nope' (editable: Sampling Time (s), Gain Value, Multiplication Type)

--console "connect(a<0>, b<0>)"
Software Initialized
connect(): unknown handle 'a'

A singular inverse: the error row is raised, and the line still yields a value (that build; since 2026-09-02 the console's inv() answers a matrix of Inf instead, as MATLAB does)

--console "y = inv([1 2; 2 4])"
Software Initialized
[ICoreRunDiagnosis] - Error - Unable to compute matrix inverse. Matrix is singular.
y = 0  # Integer

A block configured with text where a number is due, then run. The diagram is a four-line recipe file (Step → Gain, g.setConfig(Gain Value, abc)), run headlessly with docsSample --recipe, which builds it, runs it, and reports the first Run Diagnosis error:

--console "docsSample --out <scratch>/out --recipe <scratch>/badgain.txt --name badgain --steps 5"
Software Initialized
docsSample: badgain: unsampled (Unable to retrieve config Gain Value at block: ICore Blocks/Home/Gain)

The same recipe with [1 2; 3 4] as a matrix gain fed by a [1 2 3] constant:

docsSample: sizemismatch: unsampled (Invalid matrix dimensions passed to state space. New matrices were ignored.)

A global sampling time of zero (setModelConfig globalSamplingTime 0; in front of the same command) — note the Main Log line first, then the Run Diagnosis row:

Invalid sampling rate found after sampling times were processed.
docsSample: ts0: unsampled (Invalid sampling rate found. Check software log.)

And the two non-errors claimed above — a lone unconnected Gain, and a Step → Sum → Gain → Sum feedback loop — both build and run:

docsSample: 1 file written to <scratch>/out -- unconnected sampled, 5 steps at Ts = 0.100000 s
docsSample: 1 file written to <scratch>/out -- loop sampled, 5 steps at Ts = 0.100000 s

How to report a problem#

Include, in this order:

The first error row from the Run Diagnosis panel (right-click → copy; headless: the first [ICoreRunDiagnosis] - Error - line), verbatim.
The project folder — the recipe file is plain text and replays the diagram exactly; generateRecipe in the console prints the same text for the current level if you prefer to paste it.
The console line you typed, if the problem started in the console, and the modelConfig output if it started in a run.
Loggers/MainLog.log from the folder the application was started from, if it exists (see above for why it may not after a short headless run); or the Main Log window's text.
The build date of the application (Help → About).

For contributors#

The contributor pages hold the invariants behind these messages: the simulator's error-is-a-stop rule and the sampling model, the code engine's build gate, the verifier's bail paths, and the serialization guard that holds autosave off after a failed load. They are listed in this page's related: front-matter.