IMD SolutionComputing LibraryShop main store

Troubleshooting

Fixing the fd_mask error when building an MQTT library

Operating systems on the plant floor Published 7 min read

Short answer

The fd_mask error that stops a third-party MQTT library build comes from the compiler installation's C headers, not from the MQTT source. In the confirmed Automation Studio 4.12 case, the definition in types.h had been commented out during an earlier duplicate-declaration fix and never restored; restoring the supplied definition fixed the build with no library changes.

On this page
  1. Why does the fd_mask error point at a file outside my project?
  2. Where should the fd_mask type be defined?
  3. Could my own project have caused the fd_mask error?
  4. How do I check the MQTT library's dependencies?
  5. Why does the project build in one Automation Studio version but fail in another?
  6. What did the confirmed fix look like step by step?
  7. What if the header is unmodified and fd_mask is still missing?
  8. How do I keep installation headers from breaking builds again?
  9. Questions asked

When a third-party MQTT library stops building because the compiler does not recognize the fd_mask type, the fault is rarely in the MQTT source. The type belongs to the C headers of the development tool's installation, and in the confirmed case — a B&R Automation Studio 4.12 build of the libemqtt embedded client — the installation's types.h had been edited during an earlier project: its supplied fd_mask definition was commented out to silence a duplicate declaration and never restored. Uncommenting that one line fixed the build. The sections below walk the diagnosis in the order you meet it, from reading the error path to restoring the header.

Why does the fd_mask error point at a file outside my project? #

Because the library's socket layer includes the compiler installation's C headers through the include path, the compiler reports the missing type at the header line where it expected a declaration, and the full path in the diagnostic identifies the file as toolchain-owned rather than project-owned.

Open the complete diagnostic before touching anything. In the confirmed case the failing file sat inside the Automation Studio installation folder, not in the project tree — the project source had compiled to the point of pulling in that header. The decision from that single read: when the path resolves inside the installation, stop editing the MQTT source and diagnose the installation, because no change to library files can supply a type the toolchain headers fail to declare.

Where should the fd_mask type be defined? #

In the C headers that ship with the compiler — the types.h family where fd_set and its helper macros live — not in any project file, because the MQTT library only references the type and expects the environment to supply it.

On desktop Linux, glibc keeps the fd_set type, its related macros and the select declarations together in sys/select.h, and requires the fd_set member to be an array of longs. An embedded toolchain ships whatever subset of that environment the runtime supports, so the declaration's presence is a property of the installation, not of your code. The failure comes in three shapes: the definition is absent from that header set, it is present but excluded by preprocessor conditions, or it is present but has been disabled by hand. Which shape you have is decided by opening the header, never by the error text.

Could my own project have caused the fd_mask error? #

Run Find-In-Files (Ctrl+Shift+F) across the whole project for fd_mask and read the results as one of three cases: the project declares the type, the project references it with no declaration anywhere, or a project declaration duplicates the one in the installed header.

The third case is what set up the confirmed failure. A project that defined fd_mask itself collided with the header's definition, so the header's copy was commented out to get that build through, and the restoration was forgotten. Every later project that relied on the header then compiled against a toolchain silently missing the type, with no trace of the cause in the failing project. Rule this out first, because it is the one failure mode you can fix in your own sources. Decision: if the search finds a project-side definition, remove or rename it so the header's declaration stands, then verify the header itself before rebuilding.

How do I check the MQTT library's dependencies? #

Right-click the library in the Logical View, open Properties, and read the Dependencies tab: a documented third-party library lists what it needs there, and one missing dependency file can leave a referenced type undeclared even when the toolchain headers are intact.

Work the tab in this order:

  • Add every dependency the developer lists, then confirm the file carrying the required declaration is part of the software configuration, not just present on disk.
  • Confirm that file compiles before the MQTT source that uses the type — an include resolving to a file excluded from the build behaves exactly like a missing declaration.
  • If the tab is empty or vague, the requirement question goes to the library developer, because an undocumented dependency cannot be reconstructed from a compiler error.

If the dependencies check out and the project search found nothing, the remaining suspect is the installation header itself.

Why does the project build in one Automation Studio version but fail in another? #

Because each installed version carries its own header set, and in the confirmed case the older installation's types.h was simply unmodified: the project built under Automation Studio 4.10 and failed under 4.12, and comparing the two headers — not the version numbers — exposed the local edit.

The project had been upgraded from 4.7 to 4.12, which made the fault look like an upgrade regression. It was not. Version-dependent behavior is a clue that tells you which two installations to compare, nothing more. When identical source builds in one installation and fails in another on an identifier inside a system header, diff those installations' headers before blaming the release or the upgrade path.

What did the confirmed fix look like step by step? #

One line restored in one header, zero changes to the MQTT source: the fix compared the edited types.h against an unmodified installation, removed the comment markers from the supplied fd_mask definition, and the build that had failed on the type compiled clean.

The case, end to end:

  1. The libemqtt build under Automation Studio 4.12 stopped with the compiler reporting fd_mask as unrecognized, and the diagnostic's path pointed into the installation, not the project.
  2. The same project compiled unchanged under Automation Studio 4.10, which made the two installations the comparison pair.
  3. Diffing the types.h files showed the 4.12 copy's definition commented out, while the 4.10 copy and a freshly installed copy of the same release both carried it active.
  4. The comment traced back to an earlier project that declared fd_mask itself — a duplicate-declaration fix applied to the header instead of the project.
  5. Restoring the single supplied line, with no new declaration written and no library file touched, let the build complete.
Environment Result What it established
Automation Studio 4.10, unmodified headers Project compiled The source was buildable
Automation Studio 4.12, header as found fd_mask unrecognized The installation was the suspect
Automation Studio 4.12, definition restored Project compiled The edited header was the root cause

Restore before you rewrite. If the diff shows a disabled supplied definition, re-enabling it is the whole fix; a replacement declaration written from memory adds risk and removes evidence.

What if the header is unmodified and fd_mask is still missing? #

Then the toolchain genuinely lacks the declaration for the configuration you selected, and the requirement has to come from the library developer: in the examined 4.12 installation, the GCC 6.3.0 headers carried no fd_mask at all, while the GCC 4.1.2 headers declared it behind preprocessor guards.

Those guards matter diagnostically. The header withholds fd_set and related definitions when the compile defines _POSIX_SOURCE, or when a Windows winsock header has been or may be included, as signaled by _WINSOCK_H and __USE_W32_SOCKETS; in that installation the guarded block began at line 205 of types.h. Read the lines above the failing one before concluding the type never shipped — guard exclusion and absence are different problems. Do not treat a compiler-generation change as the fix, either: the observation above ran opposite to upgrade intuition, with the older toolchain carrying the declaration and the newer one lacking it. The legitimate paths, in order:

  • Obtain the declaration and platform requirements from the library developer.
  • Remove the unsupported references from the port.
  • Define the type inside the project only when its required representation is documented.

The fourth exit is architectural: publish from outside the controller. If the toolchain cannot support the library's socket layer, run the client on a fanless mini PC in the same cabinet and leave the controller serving its variables. That is the same architecture as bridging OPC UA PLC data to MQTT with an edge PC, where the box owns the broker connection.

How do I keep installation headers from breaking builds again? #

Treat the installation directory as read-only: one commented line there changes every project that installation compiles, and the failure surfaces later in an unrelated build with nothing pointing back to the edit, so duplicates get fixed on the project side, never in the shipped header.

If a diagnosis ever requires touching a shipped header, restore it the same day and write down what changed. Keep an unmodified installation, or an archived copy of the header tree, as a diff baseline — the fresh-install comparison is what made the confirmed case conclusive. After any toolchain-level fix, rebuild the project that originally forced the edit as well, to confirm the duplicate declaration it once silenced has been resolved at its source.

Questions asked

Can I define fd_mask myself in the MQTT project?

Only as a last step, and only when the library or platform developer documents the representation the type must have, because the runtime's select implementation was built against a specific layout. A project-side definition that compiles can still disagree with that layout. Rule out a disabled definition in the installation header, a missing dependency, and preprocessor guards first.

Does reinstalling the development tool fix the fd_mask error?

Only when the header was modified, because a fresh installation ships the declaration active, which is exactly what the comparison showed in the confirmed case. Reinstalling also discards any other toolchain changes and costs project reconfiguration, so diff the header against a known-good copy first and restore the single line instead of rebuilding the installation.

Why did uncommenting one line fix the entire build?

Because the failure was a missing declaration, not a logic fault. The compiler stopped at the first use of an undeclared identifier in the socket layer, so any further errors in that file were consequences of the one absent name. Once the header supplied the type again, the same code compiled without any change to the library source.

Do I need to change the MQTT library source at all?

No, not in the confirmed case and not when the header comparison shows a disabled supplied definition: the library referenced the type correctly and the environment failed to declare it. Keep the library source untouched through the diagnosis, because edits made during troubleshooting obscure which change actually fixed the build.

Keep reading

  • Troubleshooting

    Fixing MQTT cloud broker data not reaching SCADA tags

    Get the gate right first: MQTT over TLS belongs on port 8883, with the TLS mode and client identity the broker actually requires. An independent client such as MQTT Explorer on the same PC proves only its own settings, not the driver's. If the driver cannot perform the service-specific handshake Azure IoT Hub needs, no tag mapping will ever fill.

    Edge computing and IIoT

  • How-to

    Set up the MQTT Client SL library on a CODESYS controller

    MQTT Client SL is part of the CODESYS IIoT Libraries SL package. Verify the exact controller runtime and its license, pin the library version, batch JSON per asset, and set the controller clock before opening a TLS session.

    Edge computing and IIoT

  • Troubleshooting

    TwinCAT Visual Studio freezes when connected to an IPC target

    The 5 to 10 second stalls in Visual Studio are ADS timeouts on the link between the engineering PC and the IPC, not real-time or CPU problems: pointing the target at the local system or pulling the cable clears them. Work link negotiation, hostname routes, competing adapters and the ADS TCP session on port 48898, then finish with static addresses and an IP-based route.

    Operating systems on the plant floor