Detecting And Fixing Lsp Violations - Learning Module

Loading content...

0/246

Unexpected Exceptions from Subclasses — The Silent Contract Breakers

When Polymorphism Explodes

3 AM. Your pager goes off. Production is down.

You pull up the logs and see a cascade of UnsupportedOperationException errors originating from your document export pipeline. The stack trace shows:

DocumentExporter.exportAll() →
  Document.export() →
    ReadOnlyDocument.export() → THROWS UnsupportedOperationException

You designed the exporter to work with any Document. The ReadOnlyDocument class extends Document. So why is it throwing exceptions when export is called?

The answer lies in a subtle but devastating pattern: a subclass that cannot fulfill its superclass contract but was allowed to exist anyway. The ReadOnlyDocument can't be exported because... well, it was never meant to be. Someone created it to represent documents in a preview mode, and they overrode export() to throw an exception.

The hierarchy compiled. Tests passed. But the Liskov Substitution Principle was violated. And at 3 AM, that violation became your problem.

What You Will Learn

By the end of this page, you will understand how unexpected exceptions from subclasses constitute LSP violations, recognize the patterns that lead to exception-throwing overrides, and learn systematic approaches to designing hierarchies where subclasses never need to refuse operations their superclass promises.

The Exception Contract Problem

When a base class declares a method, it establishes an implicit contract: this operation is meaningful for all instances of this type. Clients write code that calls this method, trusting it will "work" according to the method's documented purpose.

When a subclass overrides that method to throw an exception—signaling "I can't do this"—it breaks this contract. The subclass is essentially saying: "I inherit the interface that promises this capability, but I don't actually have it."

exception-violation-basic
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// Base class establishes a contract: all Documents can be saved
abstract class Document {
    abstract getContent(): string;
    abstract save(): void;  // Contract: saving persists the document
}
 
// LocalDocument fulfills the contract
class LocalDocument extends Document {
    private content: string = "";
    
    getContent(): string {
        return this.content;
    }
    
    save(): void {
        // Actually saves to file system - contract fulfilled
        fs.writeFileSync(this.path, this.content);
    }
}
 
// ReadOnlyDocument VIOLATES the contract
class ReadOnlyDocument extends Document {
    getContent(): string {
        return this.content;
    }
    
    save(): void {
        // VIOLATION: Throws instead of saving
        throw new Error("Cannot save a read-only document");
    }
}
 
// Client code written against the abstraction
class AutosaveManager {
    private documents: Document[] = [];
    
    saveAll(): void {
        for (const doc of this.documents) {
            // Trusts that all Documents can be saved
            doc.save();  // Explodes when doc is ReadOnlyDocument!
        }
    }
}

The Fundamental Contradiction

A ReadOnlyDocument that throws on save() is a contradiction in terms. By extending Document, it claims to be a Document—which implies it can be saved. By throwing on save(), it admits it cannot. This internal contradiction is the essence of an LSP violation.

The hierarchy lies to its clients. The type system says "ReadOnlyDocument is a Document" and "Documents can save()". Both statements are technically true in the type system. But behaviorally, the combination is false—ReadOnlyDocuments cannot save, even though their type says they can.

This mismatch between declared type capabilities and actual runtime behavior is what makes exception-throwing overrides such dangerous LSP violations.

Common Patterns of Exception Violations

Exception-throwing overrides appear in predictable patterns. Recognizing these patterns helps you identify LSP violations during code review and design discussions.

Exception Violation Patterns

•The Unsupported Override — Method explicitly throws UnsupportedOperationException or equivalent
•The Immutable Subclass — Mutable parent with immutable child that throws on mutation
•The Null Object Gone Wrong — A 'do nothing' object that throws instead of doing nothing safely
•The Stripped-Down Version — A subclass that removes capabilities present in the parent
•The Precondition Strengthener — A subclass that adds validation the parent doesn't require
•The Mode-Dependent Exception — Methods that work only in certain object states

exception-patterns
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
// PATTERN 1: The Immutable Subclass
class MutableList<T> {
    protected items: T[] = [];
    
    add(item: T): void {
        this.items.push(item);
    }
    
    remove(item: T): void {
        const idx = this.items.indexOf(item);
        if (idx >= 0) this.items.splice(idx, 1);
    }
}
 
class ImmutableList<T> extends MutableList<T> {
    override add(item: T): void {
        throw new Error("Cannot modify immutable list");  // VIOLATION
    }
    
    override remove(item: T): void {
        throw new Error("Cannot modify immutable list");  // VIOLATION
    }
}
 
// PATTERN 2: The Stripped-Down Version
abstract class Vehicle {
    abstract accelerate(): void;
    abstract brake(): void;
    abstract reverse(): void;
}
 
class Bicycle extends Vehicle {
    accelerate(): void { /* pedal faster */ }
    brake(): void { /* apply brakes */ }
    reverse(): void {
        // Bicycles can't really reverse while moving
        throw new Error("Bicycles cannot reverse");  // VIOLATION
    }
}
 
// PATTERN 3: The Precondition Strengthener
class NumberProcessor {
    process(value: number): number {
        return value * 2;  // Works for any number
    }
}
 
class PositiveNumberProcessor extends NumberProcessor {
    override process(value: number): number {
        if (value <= 0) {
            throw new Error("Value must be positive");  // VIOLATION
        }
        return value * 2;
    }
}
 
// PATTERN 4: Mode-Dependent Exceptions
class Connection {
    private isOpen: boolean = false;
    
    open(): void { this.isOpen = true; }
    close(): void { this.isOpen = false; }
    
    send(data: string): void {
        if (!this.isOpen) {
            throw new Error("Connection not open");  // VIOLATION
        }
        // send data
    }
}
 
// Client code can't trust that send() works without checking state

Why these patterns emerge:

In each case, a developer faced a requirement that didn't fit the existing hierarchy:

"We need an immutable version" → Inherit and throw on mutation
"We need a simpler vehicle" → Inherit and throw on unsupported features
"We need stricter validation" → Inherit and add precondition throws
"Operations depend on state" → Throw when state doesn't support operation

The reflex to inherit and throw is natural—it reuses existing code with minimal apparent effort. But it creates a hierarchy that lies about its capabilities.

The Inheritance Instinct

When you find yourself writing throw new UnsupportedOperationException() in an override, stop. This is a signal that inheritance is the wrong relationship. The subclass isn't truly a specialized version of the parent—it's a different thing that happens to share some code.

The Defensive Programming Cascade

When subclasses throw unexpected exceptions, client code must defend against them. This creates a cascade of defensive patterns that spreads through the codebase, adding complexity and obscuring intent.

Defensive Cascade Effects
Stage	What Happens	Code Impact
Initial Bug	Exception surfaces in production	Incident response, hotfix deployed
Direct Defense	Try-catch added around the call	Error handling logic bloats method
Propagation	Other callers add same defense	Defensive code appears in multiple locations
Abstraction Decay	Wrappers created to 'safe-ify' calls	Additional indirection layers added
Documentation Debt	Methods documented with 'may throw' warnings	Comments replace type contracts
Testing Burden	Tests must cover exception paths for each subtype	Test complexity explodes

defensive-cascade-example
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// STAGE 1: Original clean code
function processAllDocuments(docs: Document[]): void {
    for (const doc of docs) {
        doc.save();  // Trusts the abstraction
    }
}
 
// STAGE 2: After first production incident, direct defense
function processAllDocuments(docs: Document[]): void {
    for (const doc of docs) {
        try {
            doc.save();
        } catch (e) {
            console.error(`Failed to save document: ${e.message}`);
            // What now? Skip? Retry? Fail all?
        }
    }
}
 
// STAGE 3: Abstraction decay - "safe" wrappers emerge
function safelySave(doc: Document): boolean {
    try {
        doc.save();
        return true;
    } catch (e) {
        return false;
    }
}
 
function processAllDocuments(docs: Document[]): SaveResult {
    const results = docs.map(doc => ({
        doc,
        success: safelySave(doc)
    }));
    return new SaveResult(results);
}
 
// STAGE 4: Capability checking emerges
function processAllDocuments(docs: Document[]): void {
    for (const doc of docs) {
        // Now we're type-checking - see previous lesson
        if (doc instanceof ReadOnlyDocument) {
            // Skip read-only documents
            continue;
        }
        doc.save();
    }
}
 
// STAGE 5: Full defensive meta-layer
interface SaveCapable {
    canSave(): boolean;
    save(): void;
}
 
function processAllDocuments(docs: Document[]): void {
    for (const doc of docs) {
        if ('canSave' in doc && doc.canSave()) {
            doc.save();
        } else {
            // Handle non-saveable documents
        }
    }
}
 
// The abstraction is now covered in defensive scar tissue

The cost analysis:

Each stage of the cascade adds overhead:

Stage	Lines of Code	Complexity	Maintenance
Original	4	O(1)	Trivial
Direct Defense	10	O(n) per caller	Medium
Safe Wrappers	20+	O(n²) propagation	High
Capability Checks	15+	Type-check overhead	Very High
Meta-Layer	30+	New abstraction layer	Extreme

A single exception-throwing override can multiply code complexity by 5-10x across the codebase.

Hidden Time Bomb

The cascade doesn't happen immediately. First comes the incident. Then the hotfix. Then another incident in a different context. Slowly, defensive code spreads. By the time the pattern is recognized, it's entrenched in dozens of files. The fix becomes a major refactoring effort.

Exception Specification and Contract Design

The LSP provides clear rules about exceptions in inheritance hierarchies. Understanding these rules helps you design contracts that subclasses can actually fulfill.

LSP Exception Rules

•Subclasses cannot throw exceptions that the parent doesn't throw — If the parent's method is exception-free, all overrides must be exception-free
•Subclasses can narrow exception types — If parent throws Exception, child can throw SpecificException, but not add new exception types
•Runtime exceptions blur the line — Many languages allow unchecked/runtime exceptions anywhere, making the contract implicit rather than explicit
•Documentation is contract — When language doesn't enforce exception contracts, documentation becomes the specification

exception-contract-rules
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// RULE: Methods should declare their exception behavior
 
// Parent establishes exception contract (via documentation in TypeScript)
abstract class PaymentProcessor {
    /**
     * Process a payment.
     * @throws PaymentFailedException if the payment network is unavailable
     * @throws InvalidPaymentException if payment details are invalid
     * Does NOT throw for any other reason - clients can rely on this
     */
    abstract process(payment: Payment): Receipt;
}
 
// VALID: Subclass narrows exceptions (throws fewer types)
class LocalPaymentProcessor extends PaymentProcessor {
    // Never throws PaymentFailedException (no network needed)
    // May throw InvalidPaymentException
    process(payment: Payment): Receipt {
        if (!payment.isValid()) {
            throw new InvalidPaymentException("Invalid payment");
        }
        return new Receipt(payment);
    }
}
 
// INVALID: Subclass adds new exception type
class StrictPaymentProcessor extends PaymentProcessor {
    process(payment: Payment): Receipt {
        // Parent doesn't declare this exception type!
        if (payment.amount > this.limit) {
            throw new LimitExceededException("Over limit");  // VIOLATION
        }
        return new Receipt(payment);
    }
}
 
// INVALID: Subclass throws where parent never does
class ReadOnlyPaymentProcessor extends PaymentProcessor {
    process(payment: Payment): Receipt {
        // Parent guarantees processing will occur
        throw new UnsupportedOperationException();  // VIOLATION
    }
}

The Runtime Exception Loophole

Java's checked exception system enforces exception contracts at compile time—but only for checked exceptions. RuntimeException subclasses bypass this entirely. In dynamically typed languages or with unchecked exceptions, the contract is purely documentation-based. This is why LSP violations via exceptions often slip through until production.

Designing for exception honesty:

When defining a base class or interface, consider what exceptions are part of the contract:

Operational exceptions (expected failures) — Should be declared, subclasses can narrow
Programming errors (bugs) — Unchecked, represent contract violations by the caller
System failures (unrecoverable) — Typically unchecked, represent environment issues

If a subclass needs to throw an exception that isn't part of these categories—especially "I can't do this operation"—it's a sign that the inheritance relationship is wrong.

Design Alternatives to Exception Overrides

When you're tempted to write an exception-throwing override, stop and consider these design alternatives. Each addresses the underlying need without violating LSP.

LSP-Compliant Alternatives

•Split the interface — Separate capabilities into distinct interfaces that types can implement selectively
•Use composition over inheritance — Don't inherit if you can't substitute; compose with a shared component instead
•Create a capability hierarchy — Define a richer type hierarchy that accurately models capabilities
•Use the Null Object pattern — Provide a safe do-nothing implementation instead of throwing
•Return result types — Return Result<T, E> or Optional<T> instead of throwing
•Redesign the hierarchy — Accept that the current hierarchy is wrong and fix it properly

design-alternatives
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
// PROBLEM: ReadOnlyDocument can't save but extends Document
 
// ALTERNATIVE 1: Split the interface
interface Readable {
    getContent(): string;
}
 
interface Saveable {
    save(): void;
}
 
// Now types claim only what they can do
class EditableDocument implements Readable, Saveable {
    getContent(): string { return this.content; }
    save(): void { /* actually saves */ }
}
 
class ReadOnlyDocument implements Readable {
    getContent(): string { return this.content; }
    // No save() - doesn't claim capability it doesn't have
}
 
// Client code is honest about requirements
function exportDocument(doc: Readable): void { /* ... */ }
function autosave(doc: Saveable): void { doc.save(); }
 
 
// ALTERNATIVE 2: Capability hierarchy
interface Document {
    getContent(): string;
}
 
interface EditableDocument extends Document {
    save(): void;
    edit(content: string): void;
}
 
interface ImmutableDocument extends Document {
    // Explicitly no mutation methods
    readonly createdAt: Date;
}
 
 
// ALTERNATIVE 3: Result types instead of exceptions
interface SaveResult {
    success: boolean;
    error?: string;
}
 
class Document {
    save(): SaveResult {
        // Default implementation
        return { success: true };
    }
}
 
class ReadOnlyDocument extends Document {
    override save(): SaveResult {
        // Doesn't throw - returns failure result
        return { success: false, error: "Document is read-only" };
    }
}
 
 
// ALTERNATIVE 4: Null Object pattern
interface Document {
    save(): void;
}
 
class NullSaveDocument implements Document {
    save(): void {
        // Does nothing - safely
        // Optionally logs: "Save operation ignored for read-only document"
    }
}
 
 
// ALTERNATIVE 5: Composition over inheritance
class DocumentViewer {
    private content: string;
    
    // No save() method at all - this class is for viewing
    getContent(): string { return this.content; }
    
    // If saving is needed, compose with a saver
    saveWith(saver: DocumentSaver): void {
        saver.save(this.content);
    }
}

Bad: Exception Override

•Claims capability via type
•Reveals truth at runtime
•Surprises client code
•Forces defensive patterns
•Compounds over time

Good: Honest Types

•Type declares actual capabilities
•Contract clear at compile time
•Client knows what to expect
•Polymorphism works correctly
•System remains maintainable

The Interface Segregation Connection

Notice how Alternative 1 (Split the interface) connects to the Interface Segregation Principle (ISP). LSP violations via exceptions often indicate ISP violations—the base interface is too large, forcing subtypes to 'refuse' parts of it. If you're throwing exceptions in overrides, consider whether the interface should be smaller.

Detection and Prevention Strategies

Preventing exception-based LSP violations requires both proactive design practices and detection mechanisms in your development process.

Detection Techniques

•Grep for exception throws in overrides — Search for UnsupportedOperationException, NotImplementedError, etc. in method bodies
•Code review checklist — Ask 'Does this override ever throw where the parent doesn't?' for every override
•Contract testing — Write tests that use base class references but test with all concrete implementations
•Static analysis rules — Some analyzers can detect methods that always throw immediately
•Runtime monitoring — Track exceptions by class and method to identify patterns

detection-commands
Bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Find common exception-throwing override patterns
 
# TypeScript/JavaScript
grep -rn "throw new.*Unsupported" --include="*.ts" src/
grep -rn "throw new.*NotImplemented" --include="*.ts" src/
grep -rn "throw new Error.*cannot.*" --include="*.ts" src/
grep -rn "throw new Error.*not supported" --include="*.ts" src/
 
# Python
grep -rn "raise NotImplementedError" --include="*.py" src/
grep -rn "raise UnsupportedOperation" --include="*.py" src/
grep -rn "raise.*cannot.*" --include="*.py" src/
 
# Java
grep -rn "throw new UnsupportedOperationException" --include="*.java" src/
grep -rn "throw new NotImplementedException" --include="*.java" src/
 
# Find override methods that might be problematic
grep -rn "@Override" --include="*.java" -A5 src/ | grep -B5 "throw new"

Contract testing pattern:

Write tests that exercise the base class contract with every concrete implementation:

contract-testing
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// Contract test ensures all implementations fulfill the contract
describe('Document contract', () => {
    // All concrete implementations to test
    const implementations: Document[] = [
        new LocalDocument('/tmp/test.txt'),
        new CloudDocument('bucket/key'),
        new ReadOnlyDocument('content'),  // This test will fail!
        new CachedDocument(new LocalDocument('/tmp/test.txt')),
    ];
    
    implementations.forEach(doc => {
        describe(`${doc.constructor.name}`, () => {
            it('should save without throwing', () => {
                // This is the contract test
                expect(() => doc.save()).not.toThrow();
            });
            
            it('should return content after save', () => {
                doc.setContent('test');
                doc.save();
                expect(doc.getContent()).toBe('test');
            });
            
            // More contract tests...
        });
    });
});
 
// When ReadOnlyDocument is tested, the test fails
// This surfaces the LSP violation before production

Page Complete

You now understand how exception-throwing overrides violate LSP, the defensive cascade they create, exception contract rules, and design alternatives. The next page explores partial implementations—another form of LSP violation where subclasses provide incomplete behavior.

Summary: Exceptions as Contract Breakers

Key Takeaways

•Exception-throwing overrides break substitutability — When a subclass throws where the parent doesn't, clients can't trust the abstraction
•Common patterns include unsupported operations, immutable subclasses, and precondition strengthening — Recognize these as design smells
•The defensive cascade is expensive — From try-catch to wrappers to meta-layers, exception violations compound codebase complexity
•LSP has clear exception rules — Subclasses can narrow but not widen exception specifications
•Alternatives exist — Interface segregation, composition, result types, and null objects avoid the need for exception overrides
•Detection requires systematic approach — Grep patterns, contract tests, and code review checklists catch violations early

Next up:

The following page examines partial implementations—subclasses that don't fully implement their inherited interface, leaving some methods as stubs, no-ops, or returning default values that don't satisfy the contract's intent.