Troubleshooting
Fixing CODESYS Modbus TCP server exception 0x0002
Short answer
Exception 0x0002 means the CODESYS Modbus TCP server holds no point at the address the client requested. The Data Model start-address fields are offsets within each data type's standard range, so entering 10001 for Discrete Inputs pushes the first bit to reference 20002. Set each start address to 0, confirm the client's notation, then prove one point with a scanner.
On this page
- What exception 0x0002 actually reports
- The start-address field is an offset, not the reference
- Worked example: discrete input 10001 with 10001 as the start address
- Set the start addresses to zero and keep the mapping
- If the exception survives zero offsets
- Symptoms and where each one points
- The decision for each case
- Questions asked
Exception 0x0002 from a CODESYS Modbus TCP server means Illegal Data Address: the request arrived, the server understood it, and no point in its data model sits at the address you asked for. When an HMI and a desktop Modbus scanner both fail on the same reference — even a single poll of discrete input 10001 — the fault is almost always the server's own address map, not the network and not either client. The start-address fields on the server's Data Model page are offsets within each data type's standard Modbus range, so typing the full reference 10001 into the Discrete Inputs field moves the whole area out of reach instead of putting your first bit at 10001. Set every start address back to 0, leave the variable mapping alone, confirm each client's notation, and prove one point before widening the test.
What exception 0x0002 actually reports #
The Modbus application protocol specification (V1.1b3) defines exception code 02, Illegal Data Address: the server received a well-formed request for an address — or for an address-plus-quantity combination — that falls outside the points it actually holds. The server answers normally on the wire and the controller logs nothing, so a working TCP connection and a responding device prove transport only, never that a point exists.
Two independent clients failing on the same reference is the strongest clue you get. One misconfigured client fails alone; a wrong value in the server's data model fails for every client that talks to it. Sort server-side from client-side with that rule before you change any number.
The start-address field is an offset, not the reference #
In the device tree, the Modbus TCP server device carries a Data Model page among its General settings, with a start-address field for each data type: coils, discrete inputs, input registers and holding registers. Every field defaults to 0, and each one is an offset inside that area's standard range. Discrete Inputs at 0 exposes the first bit at the conventional reference 10001, and any other value shifts that start upward by exactly that many references. The offset never replaces the area's base, so a full reference number has no business in any of these fields.
The server's I/O mapping screen shows IEC addresses such as %QX40.3 next to each channel. Those locate the mapped variable inside the IEC program; they are not Modbus references, and nothing should be edited to make them look like one. The mapping assigns your variable to a channel, while the Data Model alone decides which Modbus reference that channel answers at.
Keep the request's data area aligned too: a discrete-input read reaches only the discrete-input area, never coils or registers. How a tool's display number, the 1-based reference and the 0-based address on the wire fit together is the subject of this page on decoding Modbus register addresses across 0-based and 1-based maps.
Worked example: discrete input 10001 with 10001 as the start address #
The inputs:
- Start address entered for Discrete Inputs: 10001 — the commissioning value that produced the exception.
- Client request: one discrete input at reference 10001, from a 1-based client.
- Discrete-input base: reference 10001, the area's conventional start; the classic area runs from 10001 through 19999.
The rule in words: the server exposes its first discrete input at the base plus the start-address offset, so a requested reference exists only when it lands between base + offset and the end of the mapped block.
The arithmetic: first exposed reference = 10001 + 10001 = 20002 references. The client asks for reference 10001, which sits 10001 references below the first point the server holds (20002 − 10001 = 10001), so the server finds no such address and answers with exception 02.
The result: the poll fails for every client at once, because the miss lives in the server's offset, not in any client.
The decision: any non-zero offset n moves the first bit to 10001 + n references and breaks a standard map, and only an offset of 0 puts the first discrete input at 10001. Set Discrete Inputs to 0; the poll of 10001 then lands on the first channel and passes.
Set the start addresses to zero and keep the mapping #
- Record the failing request before changing anything: data area, reference, quantity, the client's notation, and the current Data Model values.
- Open Device Tree > ModbusTCP_Server > General > Data Model and set the start address of each data type you use to 0 — for the failing point, Discrete Inputs = 0.
- Open the server's I/O mapping tab and confirm your variable is still assigned to the first discrete-input channel; leave the IEC address untouched.
- Download or activate the project, then poll one point at reference 10001 from a desktop Modbus scanner — a scanner shows the raw exception and lets you change area, address and quantity in seconds.
- Poll the same point from the HMI and compare. If the mapped variable drives output hardware, put it in a harmless state through the project's own commissioning path before you toggle it, and tell anyone within reach of the machine.
- Matching bits from scanner and HMI show that both clients address the same server point.
A passing read proves the address is accepted, not that the right variable sits behind it. Set the variable to a known state and watch the returned bit follow; if it does not, correct the I/O mapping and leave the offset at 0.
If the exception survives zero offsets #
The port layout is rarely the culprit — a CODESYS controller can serve Modbus TCP on its second Ethernet port next to whatever the first port carries, the arrangement described in how a PLC runs two Modbus networks at the same time. When one point still returns 02, work down this list:
- Unit identifier: Modbus TCP still carries a unit ID in every request, and some equipment answers only to one specific value, reporting a mismatch as this same Illegal Data Address exception. Set the client's unit ID to the value the server expects.
- Data area: check that the request's function matches the mapping. A holding-register read cannot reach a variable mapped to a discrete-input channel, and the exception looks identical.
- Notation: the same point is entered as reference 10001 in a 1-based tool and as 0 in a 0-based one. Read one known live point at both settings; whichever returns data settles that client's convention, and a 0-based client needs every address one lower than the reference. Modbus register numbering in 0-based, 1-based and reference form explains where the conventions come from.
- Quantity: start at one point and grow. A block read that runs past the end of the mapped area raises the same exception from a perfectly valid start address.
Symptoms and where each one points #
| Symptom | Where the fault sits | The move that fixes it |
|---|---|---|
| Scanner and HMI both return 02 at 10001 | Server data model offset | Set the Discrete Inputs start address to 0 |
| Read passes but the bit is wrong | Variable assignment or data area | Check the I/O mapping and the request's function code |
| One client fails while another reads the same point | That client's notation or unit ID | Fix the client; leave the server alone |
| One point passes, a 100-point block fails | Block runs past the end of the map | Shorten the quantity or extend the mapped block |
The decision for each case #
- Standard commissioning map, clients expecting references such as 10001: every Data Model start address 0, and the first discrete input answers at 10001.
- A map that must begin inside an area: set the offset to the number of references below your first point — 200 puts the first bit at 10201 — and enter those shifted references in every client.
- Exception 02 after the offsets are 0: the server is finished; correct the client's unit ID, data area, notation or quantity, one change at a time.
- A clean read that returns the wrong bit: the offset is right and the mapping is not; reassign the variable on the server's I/O mapping tab.
Questions asked
My start address is valid, so why does a block read still return exception 02?
The Modbus specification lets the server reject a request when the start address plus the quantity runs past the end of its map. A request for 100 discrete inputs beginning at 10001 needs points through 10100; if only the first 32 are mapped, the combination fails even though 10001 alone is fine. Cut the quantity to 1 and grow it until the exception returns — the last good count marks the end of the mapped block. A read request also tops out at 2000 bits or 125 registers.
Which reference range belongs to each Modbus data area?
Coils sit at references 00001 to 09999 and read or write with functions 01 and 05. Discrete inputs sit at 10001 to 19999 and read with function 02. Input registers sit at 30001 to 39999 and read with function 04. Holding registers sit at 40001 to 49999 and read or write with functions 03, 06 and 16. Expanded six-digit references extend the areas, for example discrete inputs from 100001 to 165536. The leading digit names the area.
Can I keep 10001 in the start-address field and change the client instead?
No client can reach the point as entered. With an offset of 10001 the first discrete input sits at 20002, but the classic area ends at 19999 and expanded six-digit references begin at 100001, so nothing in between is a valid discrete input in normal tools. Set the offset to 0 instead; the standard map keeps every HMI, scanner and future client reading the same references.
Why do some tools display 0x0002 while others show exception code 2?
On the wire, an exception response carries the requested function code with its highest bit set, then one byte of exception code — here 02. Tools print that pair differently: some show 0x0002, some show exception 2, some spell out Illegal Data Address. All three describe the same server answer, so a 02 on a scanner and a 0x0002 on an HMI are one fault, not two.