Delphi EAssertionFailed — What It Means & How to Fix It

What Does This Error Mean?

EAssertionFailed is raised when an Assert() call finds that its condition is False. Assert() is a debugging tool — it checks that a condition your code assumes to be true actually is true. This exception only fires in debug builds; in release builds, Assert() calls are removed by the compiler.

Affected Models

Delphi 10.4 Sydney
Delphi 11 Alexandria
Delphi 12 Athens
Embarcadero RAD Studio
Free Pascal / Lazarus

Common Causes

An Assert() condition is False — the assumption written into the assertion has been violated
A function received an argument outside the expected range that was not validated before calling Assert
An object is in an unexpected state that the developer did not anticipate
A loop or algorithm produced a value outside its guaranteed bounds
Code called in the wrong order violated a precondition guarded by Assert

How to Fix It

When EAssertionFailed fires in the debugger, note the file name and line number shown in the exception dialog. Navigate to that line to see what condition was asserted.

Assert(Condition, 'Message') — the second parameter is optional but makes it much easier to understand what was expected.
Read the failed condition to understand what assumption was violated. For example: Assert(Index >= 0) means the code expected a non-negative index, but received a negative one.

The condition in the Assert tells you exactly what the developer assumed would always be true at that point.
Trace backwards to find where the bad value came from. Check the inputs to the function or method where the assertion failed — which caller passed the unexpected value?

Use the call stack in the debugger to walk backwards through the calling chain.
Fix the root cause: validate input at the point it enters the system (from the user, a file, a database, or another function) so invalid values never reach the assertion.

Assertions document assumptions. If an assumption is violated, the data flow needs to be fixed, not the assertion removed.
Once the root cause is fixed, verify the assertion passes consistently by running the test scenario again in debug mode. Do not disable assertions to silence the error.

Assertions are disabled in release builds automatically via {$ASSERTIONS OFF}. They have zero cost in production and are pure safety in debug.

When to Call a Professional

EAssertionFailed is not a bug in itself — it is a signal that a bug exists somewhere. Read the assertion message carefully: it tells you the file name, line number, and (if provided) the condition that failed. Fix the root cause — the data or logic that violated the assumption — rather than removing or weakening the assertion.

Frequently Asked Questions

Will EAssertionFailed occur in a release build sent to customers?

No. In release builds, Delphi compiles with {$ASSERTIONS OFF} by default, which removes all Assert() calls completely. EAssertionFailed only fires in debug builds. This means assertions are a developer-only tool and have no impact on your end users.

Should I use Assert() or raise an exception manually?

Use Assert() to check programming assumptions — conditions that should always be true if the code is written correctly. Use explicit exception raising (raise EArgumentException.Create(...)) for runtime conditions that depend on external input and can legitimately fail. Assertions say 'this is a bug if false'. Exceptions say 'this is an expected error condition'.

Can I add a custom message to make EAssertionFailed easier to diagnose?

Yes. Assert() accepts an optional second parameter: Assert(Value > 0, 'Value must be positive, got: ' + IntToStr(Value)). The message is included in the exception and shown in the debugger dialog. Always add a descriptive message — it saves significant debugging time.