---

name: inject-faults description: "Add, configure, and manage faults on Simulink, Simscape, and System Composer model signals for robustness analysis and safety validation. Use when injecting faults (stuck, noise, gain, offset) onto block inports/outports, enabling fault simulation, or analyzing fault effects. Covers sensor failures, signal corruptions, actuator faults, FMEA validation, and robustness testing. Requires Simulink Fault Analyzer." license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: version: "1.0" author: MathWorks

Fault Injection

Use evaluate_matlab_code with the Simulink.fault API to programmatically inject faults into Simulink models. Faults override signal values at block ports to simulate hardware failures, sensor faults, and actuator malfunctions.

When to Use

• Injecting sensor stuck-at faults, noise, or bias for safety analysis (Simulink, Simscape, System Composer)
• Validating FMEA failure modes through simulation
• Testing controller robustness against actuator or sensor failures
• Adding fault placeholders (without behavior) for FMEA traceability before defining fault logic
• Configuring fault trigger conditions (timed, conditional, always-on)
• Creating fault scenarios for automated testing
• Comparing nominal vs. faulted behavior
• Linking faults to FMEA failure mode cells
• Generating fault specification reports
• Exporting models with embedded fault behavior for teams without Simulink Fault Analyzer
• Registering custom fault behavior libraries
• Synchronizing (also called resync / sync / synchronize faults / update fault references) fault information from referenced models, subsystems, or linked libraries into a parent model

When NOT to Use

• Creating FMEA spreadsheets or safety analysis documents -> use manage-safety-analysis
• Building or editing model structure -> use building-simulink-models
• Running standard (non-faulted) simulations -> use simulating-simulink-models
• Writing pass/fail tests -> use testing-simulink-models

Probe

hasFA = ~isempty(which('Simulink.fault.addFault'));
fprintf('Simulink Fault Analyzer available: %d\n', hasFA);

Key Concepts

• Fault: A modification applied to a block port (inport or outport) that overrides the signal value.
• Fault without Behavior: A placeholder that documents a failure point but cannot be simulated.
• Fault with Behavior: A fault with an associated behavior model that can be simulated (see references/fault-behaviors.md).
• Fault Model: The .slx file containing fault behavior subsystem(s).
• Trigger: When the fault activates (Always On, Timed, Conditional, Manual).
• Fault Info File: <ModelName>_faultInfo.xml stores all fault metadata alongside the model.

Critical Constraints

1. Faults attach to block PORTS, not blocks. You must get the port handle via get_param(blockPath, 'PortHandles').
2. NEVER directly edit _faultInfo.xml files. Always use MATLAB APIs to modify fault definitions.
3. Fault names must be valid MATLAB identifiers (no spaces, slashes, or special characters). Use camelCase or PascalCase.
4. The fault behavior model name (first arg to addBehavior) must also be a valid MATLAB identifier.
5. NEVER use Simulink.fault.deleteAll or Simulink.fault.deleteFault to toggle faults on/off for simulation. Deleting faults destroys fault objects, their behavior models (.slx files), and their traceability links permanently. Use Simulink.fault.injection(model, false) to disable ALL fault injection for a nominal run, and Simulink.fault.injection(model, true) to re-enable. Use Simulink.fault.enable(modelElement, false) to disable faults on specific elements.
6. Not supported: Faults inside Stateflow charts, fault models, or observer models.

Workflow

1. Understand the model. Use model_overview and model_read to identify fragile signal paths -- single-point actuators, sensor feedback, computed quantities with wide fan-out.
2. Pre-flight check. Query compiled port properties to confirm signal compatibility. If the model is not already compiled, ask the user before compiling. See references/preflight-and-adding-faults.md.
3. Get port handles. Faults attach to port handles, not block paths. Use get_param(blk, 'PortHandles').
4. Add fault. Call Simulink.fault.addFault(portHandle, Name=..., Description=...). See references/preflight-and-adding-faults.md.
5. Add behavior. Call addBehavior(fault, modelName, FaultBehavior='mwfaultlib/...'). See references/fault-behaviors.md.
6. Configure trigger. Set fault.TriggerType and the corresponding properties (e.g., StartTime for Timed, Conditional for Conditional, TriggerActive for Manual). See references/triggers-and-conditionals.md.
7. Save. Call Simulink.fault.save('ModelName').
8. Simulate. Enable injection with Simulink.fault.injection(mdl, true) then sim(...). See references/simulation-workflows.md.

Guardrails

Always

• Use model_read to identify target blocks before injecting faults
• Check compiled port info before creating faults (see references/preflight-and-adding-faults.md)
• Add behavior BEFORE setting trigger properties
• Save with Simulink.fault.save('ModelName') after any fault changes
• Verify fault is active before running faulted simulation with activate(fault)
• Disable fault injection after analysis with Simulink.fault.injection(mdl, false)
• Verify test input signals are non-zero at fault injection points
• Check bus compatibility before choosing a mwfaultlib behavior

Never

• Use the Simulink.fault.Fault() constructor -- use Simulink.fault.addFault() instead
• Pass library block paths (e.g., mwfaultlib/Stuck-at-Ground) as the fault model name argument to addBehavior -- use the FaultBehavior name-value pair
• Assume fault simulation is off -- verify before each nominal run
• Violate any item in the Critical Constraints section

Ask First

• Before modifying the design model for any reason (adding blocks, changing sample times, reconnecting signals)
• Before enabling faults on a model that may be shared (it modifies model behavior)
• Before deleting existing faults (the behavior model .slx is also deleted)
• Before enabling fault.Persistent = true -- it makes the fault irreversible during simulation

Troubleshooting

| Issue | Cause | Fix | |-------|-------|-----| | Assertion failed in Simulink.fault.Fault() | Do not use the Fault() constructor directly | Use Simulink.fault.addFault(portHandle, Name=..., Description=...) instead | | Fault name must follow MATLAB variable naming conventions | Name contains spaces or special chars | Use camelCase/PascalCase with no spaces (e.g., SensorStuckAtZero) | | Invalid name for a fault model | Behavior model name has invalid characters | Use a simple MATLAB identifier (e.g., StuckAtZero, not Stuck-at-Zero) | | Unable to add fault... only to block input or output ports | Passed a block path/handle instead of port handle | Use ph = get_param(blockPath, 'PortHandles'); ph.Outport(1) | | Target signal is a continuous-time signal | Fault Analyzer cannot inject on continuous signals going to continuous blocks | See Continuous-Time Signal Decision Tree in references/advanced-operations.md | | Output dimensions do not match or Data type mismatch | Fault constant size/type ≠ target signal | See "Vector and Matrix Fault Values" in references/fault-behaviors.md | | Bus signal fault fails with non-Ground behavior | Most mwfaultlib behaviors are scalar-only | Use Stuck-at-Ground for full bus, or use BusElement to target individual elements | | Multiple faults on same port but only one fires | Only one fault per port is active at a time | Use activate(fault) to select, or use different StartTime values | | Fault exists but simulation runs nominally | Fault injection not enabled or fault not active | Call Simulink.fault.injection('Model', true) and activate(f) |

Reference Files

| File | Contents | |------|----------| | references/preflight-and-adding-faults.md | Port inspection, compile checks, adding faults, port handle resolution, fault object properties/methods | | references/fault-behaviors.md | Built-in behaviors, custom behaviors, bus faults, vector/matrix faults, discovery, data inport source | | references/triggers-and-conditionals.md | Trigger types, conditional creation, conditional/symbol object properties | | references/simulation-workflows.md | Running simulations, nominal vs. faulted comparison, selective fault isolation | | references/advanced-operations.md | FMEA linking, reports, export, deletion, continuous-time workarounds, synchronizing faults from referenced models/subsystems/libraries | | references/test-case-integration.md | Adding fault sets to Simulink Test cases (R2024a+) |

---

Copyright 2026 The MathWorks, Inc.

---