Revit Failure Handling

Revit Failure Handling

RevitApiContext.BeginFailureSuppressionScope returns a disposable scope that resolves or cancels Revit failures. Use it only for a known failure the operation can safely handle — never to make an unknown failure appear successful.

When to use

• A predictable warning or recoverable error blocks a headless operation (opening, family load, transaction commit).
• Reviewing that suppression is bounded to the operation that raises the failure.

When not to use

• The interruption is a UI dialog, not a failure — use RevitContext.BeginDialogSuppressionScope.
• The API is being called from outside the API context — dispatch the work through a Toolkit external event.

Workflow

Step 1: Bound the suppression scope

Wrap only the operation that owns the expected failure; leave unrelated work outside the scope. The scope hooks the application-level FailuresProcessing event; it covers both a transaction commit and a document open.

using (RevitApiContext.BeginFailureSuppressionScope())
{
    using var transaction = new Transaction(document, "Operation");
    transaction.Start();
    // ... operation that raises the expected failure
    transaction.Commit();
}

Opening a file can raise the same recoverable warnings. In an unattended or headless host (for example Autodesk Design Automation) no user can dismiss the warning; open the document inside the scope:

using (RevitApiContext.BeginFailureSuppressionScope())
{
    var document = RevitApiContext.Application.OpenDocumentFile(path);
}

Step 2: Choose resolve or cancel

The default resolves resolvable failures. Pass resolveErrors: false when the caller must observe unresolved errors, not auto-resolve them.

Step 3: Verify

Assert the resulting document or artifact is valid, and confirm an unrelated failure still reaches the normal error boundary.

Validation

• The suppressed failure is known and expected.
• The scope covers one bounded operation, not unrelated work.
• The resulting model or file remains valid.
• Unrelated failures remain observable.

Common Pitfalls