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/ICoreSDK/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.

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 block rate but the solver is variable-step, so the rate is ignored	expected; switch to a fixed-step or discrete solver if you want the rate honoured
`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
`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 or a console `inv()` met a singular matrix — the run continues with the value the message says (see the console run below)	see Numerics — what the solver will and will not do for what the decompositions return
`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
My loop is one sample slower than in Simulink	not a fault: a feedback edge in ICoreBlocks always carries one cycle of delay	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: invalid matrix literal: [1 2; 3]` (`ICoreExpressionEvaluator.cpp`)	ragged rows in a bracket literal used as an expression	every row needs the same number of entries
`x = [1 2; 3]` succeeds and prints `x = '[1 2; 3]' # String`	in an assignment a bracket literal is stored verbatim and typed afterwards; a ragged one becomes a String, silently (`ICoreCommandWindow.cpp`, `tryAssignment`)	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: division by zero`	scalar `/` by 0	—
`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 and scalars (use tf(num,den) for a rational)`	you divided two polynomials	build the transfer function 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

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: invalid matrix literal: [1 2; 3]

--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

--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.