staad-errors

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}")