STAAD.Pro Error Handling

Errors Are Reported Automatically

execute_code wraps your whole script in a top-level handler: any uncaught exception is captured and returned as success: false with the (sanitized) error message plus whatever you printed before it. You do NOT need `try/except` just to report a failure — let it propagate and read the error from the tool result.

Use try/except inside a script only when it changes control flow, e.g.:

• skipping a bad item inside a bulk loop so the rest keep processing
• providing a fallback value (e.g. version-gated features) and continuing

Sandbox Limitation

In the MCP sandbox, import is blocked. You cannot import typed exception classes from openstaadpy.os_analytical.oserrors. Instead, catch generic Exception and inspect the message or code.

Clear COM Errors

The openstaadpy wrapper wraps COM objects in a proxy layer that turns cryptic COM failures into actionable messages. If a COM method is missing or fails, the error typically tells you to update STAAD.Pro to the latest version — this usually means the connected STAAD instance is older than the function requires (see staad-core → Version Compatibility), not a coding mistake.

Return Contracts

Many methods raise on failure — call them directly and let execute_code surface any error. This applies to the Assign* methods and the support create/assign/query/delete methods, which return True on success and raise on failure:

prop.AssignBeamProperty(beam_ids, prop_id)   # True on success; raises on failure

Some query/getter methods still return negative integers on error instead of raising — for those, check the sign:

shape = prop.GetShapeCode(country, name)
if isinstance(shape, int) and shape < 0:
    print(f"Section not found (code {shape})")

Robust Model Building Pattern

Catch per-item inside a loop so one bad entity doesn't abort the whole batch:

geo = staad.Geometry

def safe_add_beam(start, end):
    try:
        return geo.AddBeam(start, end)
    except Exception as e:
        print(f"  Beam ({start}->{end}) skipped: {e}")
        return None

for s, e in [(1, 2), (2, 3), (3, 99)]:
    bno = safe_add_beam(s, e)
    if bno:
        print(f"Added beam {bno}")

Common Error Code Groups

Named Error Classes

These surface as raised exceptions (the message names the condition). In the sandbox, catch generic Exception and read the message:

Tips

• Always check out.AreResultsAvailable() before querying results
• Let failures propagate — execute_code returns the error; only add try/except for loop-skip or fallback control flow
• Print intermediate values (node IDs, beam IDs, property IDs) to diagnose failures
• If a function returns -999, the operation was not performed (e.g., member not designed)

Gotchas

• In standalone Python, you can from openstaadpy.os_analytical.oserrors import OsBeamNotFound — but NOT in the MCP sandbox
• execute_code already catches uncaught exceptions — do NOT wrap a single call in try/except just to print the error
• Some methods silently return 0 even when something went wrong (e.g., UpdateStructure on read-only paths)
• The Assign* methods (AssignBeamProperty, AssignDesignCommand, AssignDesignParameter, AssignDesignGroup) and support create/assign/query/delete methods raise on failure and return True on success — do NOT check if result < 0 for these
• Negative return codes still apply to many getter methods — always check if result < 0 for those
• A "update STAAD.Pro" error usually means the connected instance is older than the called function requires (see staad-core → Version Compatibility)