SWMM5 Error Message Code Summary

 Below is a step-by-step overview of this SWMM 5.2 error message listing. Each ERR(code, "message") line defines an error code and accompanying text that SWMM can output if a particular error condition occurs during a simulation. By centralizing them, the code can easily map each numerical code (e.g., 101, 201, 501, etc.) to a descriptive text message to help users diagnose what went wrong.

---

1. What These Error Macros Represent

1. ERR(XXX, "message")

   • A macro typically expands into data or function calls that store an integer error code (e.g., 101) along with a format string (like "\n ERROR 101: memory allocation error.").
   • This allows SWMM to:
     1. Identify each unique error scenario (like an invalid parameter or a missing file).
     2. Print a meaningful message explaining the issue.

2. These errors often:

   • Refer to specific objects (like a Node or Link), using %s placeholders for IDs.
   • Signal a missing or invalid input condition, a file read/write issue, or a runtime failure in the solver.

---

2. General Format: ERR(error_code, "Error message")

• The error_code is an integer (e.g., 101, 203, 501).
• The "Error message" is a string that SWMM can display to the user, often including a format specifier (%s) for an object name.

---

3. Specific Examples and Groups

1. Memory/Runtime Issues

   ERR(101,"\n  ERROR 101: memory allocation error.")
   ERR(105,"\n  ERROR 105: cannot open ODE solver.")
   ERR(107,"\n  ERROR 107: cannot compute a valid time step.")
   

   • 101: The program could not allocate enough memory.
   • 105: The solver for ordinary differential equations couldn’t open (some internal module).
   • 107: The dynamic solver can’t find a stable time step.

2. Link and Node Geometry

   ERR(103,"\n  ERROR 103: cannot solve KW equations for Link %s.")
   ERR(111,"\n  ERROR 111: invalid length for Conduit %s.")
   ERR(112,"\n  ERROR 112: elevation drop exceeds length for Conduit %s.")
   ERR(113,"\n  ERROR 113: invalid roughness for Conduit %s.")
   ERR(115,"\n  ERROR 115: adverse slope for Conduit %s.")
   

   • Usually triggered if the geometry data for a conduit is physically impossible (e.g., negative length, offset bigger than length).

3. Outlets and Dividers

   ERR(133,"\n  ERROR 133: Node %s has more than one outlet link.")
   ERR(135,"\n  ERROR 135: Divider %s does not have two outlet links.")
   ERR(139,"\n  ERROR 139: Regulator %s is the outlet of a non-storage node.")
   

   • Dividers, outfalls, or special regulators have constraints on how many inlet/outlet links they can have.

4. Flow Routing

   ERR(117,"\n  ERROR 117: no cross section defined for Link %s.")
   ERR(119,"\n  ERROR 119: invalid cross section for Link %s.")
   ERR(131,"\n  ERROR 131: the following links form cyclic loops ...")
   

   • If a link is missing a cross section or there’s a loop in the drainage network, these errors show up.

5. Rainfall, Gages, and RDII

   ERR(156,"\n  ERROR 156: ambiguous station ID for Rain Gage %s.")
   ERR(159,"\n  ERROR 159: recording interval greater than time series interval for Rain Gage %s.")
   ERR(155,"\n  ERROR 155: invalid sewer area for RDII at node %s.")
   

   • Problems with rain gage data or infiltration/inflow (I/I) unit hydrograph data.

6. Mass Balance

   ERR(10, "some older format ...")
   // Actually not seen, but you see "ERROR 10" is used as a partial code in "errorcode = 10" scenarios.
   

   • If the solver finds an inconsistent mass balance, it might raise certain error codes.
   • Not all codes are explicit for mass balance, but you'll see references to potential mass/flow issues in lines like 131 or 107.

7. File Reading/Writing

   ERR(303,"\n  ERROR 303: cannot open input file.")
   ERR(305,"\n  ERROR 305: cannot open report file.")
   ERR(307,"\n  ERROR 307: cannot open binary results file.")
   ERR(309,"\n  ERROR 309: error writing to binary results file.")
   ERR(311,"\n  ERROR 311: error reading from binary results file.")
   

   • Opening or writing files fails: user lacks permission, path is invalid, or the file is locked.

8. Interface Files

   ERR(313,"\n  ERROR 313: cannot open scratch rainfall interface file.")
   ERR(315,"\n  ERROR 315: cannot open rainfall interface file %s.")
   ERR(319,"\n  ERROR 319: unknown format for rainfall data file %s.")
   ERR(331,"\n  ERROR 331: cannot open hot start interface file %s.")
   

   • SWMM can use additional “interface files” (rainfall, runoff, hotstart, etc.). If they can’t be opened or are incorrectly formatted, these errors occur.

9. Climate Files

   ERR(336,"\n  ERROR 336: no climate file specified for evaporation and/or wind speed.")
   ERR(337,"\n  ERROR 337: cannot open climate file %s.")
   ERR(338,"\n  ERROR 338: error in reading from climate file %s.")
   

   • If a climate file (with temperature, evaporation data) is needed but missing or unreadable.

10. Inconsistent or Out-of-Sequence Data

ERR(173,"\n  ERROR 173: Time Series %s has its data out of sequence.")
ERR(223,"\n  ERROR 223: Transect %s has too few stations.") 
ERR(225,"\n  ERROR 225: Transect %s has too many stations.")

• SWMM needs sorted or properly formatted data. If e.g. station cross-section data is out of order or incomplete, these errors appear.

11. Input Format or Parsing

ERR(200,"\n  ERROR 200: one or more errors in input file.")
ERR(203,"\n  ERROR 203: too few items ")
ERR(205,"\n  ERROR 205: invalid keyword %s ")
ERR(209,"\n  ERROR 209: undefined object %s ")

• The user’s input file is incorrect or references an unknown object or parameter.

12. API-Specific Errors

ERR(500,"\n  ERROR 500: System exception thrown.")
ERR(501,"\n  API Error 501: project not opened.")
ERR(502,"\n  API Error 502: simulation not started.")
ERR(503,"\n  API Error 503: simulation not ended.")
ERR(509,"\n  API Error 509: invalid time period.")

• These are used by the SWMM 5.2 API (functions in swmm5.h or swmm_output.h), indicating usage errors (like calling certain functions before swmm_open(...) or after swmm_close(...)).

---

4. How SWMM Uses These Error Messages

• Internally, SWMM sets an error code in memory (like errorcode = 309;), then prints or logs the corresponding message.
• If an error references an object (like a Node or Link), SWMM uses %s in the message to insert the object’s ID.

---

5. Key Takeaways

1. Centralized: All SWMM errors are listed in one place.
2. Codes range from around 100–500, each addressing a specific error scenario:
   • 100s often cover geometry or data errors,
   • 200s for invalid inputs or missing data,
   • 300s for file I/O problems,
   • 500s for API or system-level exceptions.
3. Meaningful: Each line describes precisely what the user or developer must fix (like “invalid slope” or “file missing”).
4. Integration: SWMM typically uses them in macros or string lookups, so the code can easily produce user-friendly messages.

By analyzing these lines, one can see the breadth of potential pitfalls in SWMM’s input data (like negative slopes, cyclical loops, out-of-sequence data) or runtime issues (like memory allocation or read/write failures).