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

There are three contracts, and they are not consistent across the API — check the owning skill before assuming which one applies.

1. Raises on failure — most Create* functions, nearly all Get* functions, and the support create/assign/query/delete methods. Call them directly and let execute_code surface the error:

prop_id = prop.CreateBeamPropertyFromTable(1, 'W14X120', 0, 0.0, 0.0)   # raises on failure

2. Returns a silent bool — notably AssignBeamProperty, AssignMemberSpecToBeam, RemovePropertyFromBeam, RemoveMaterialFromBeam and the RemoveMember*SpecFromBeam family. These never raise; a failed call is indistinguishable from a no-op unless you check:

if not prop.AssignBeamProperty(beam_ids, prop_id):
    print('assignment reported failure')