= Attribute 0 is Invalid
-This error indicates that a packet can't be processed as expected and means that:
+This error indicates that a packet can't be processed as expected and
+means that:
- * the client is completely broken, or
+* the client is completely broken, or
+* the packet doesn't follow the RADIUS standards.
- * the packet doesn't follow the RADIUS standards.
-
-RADIUS packets need to follow a format defined by RADIUS RFCs. These xref:developers:rfc/index.adoc[RFCs] standardise how users are authenticated on a network. If a packet doesn't meet the basic format requirements, it may show a problem with the client or the packet itself. For example, the client could send wrong or incomplete info. The packet might get corrupted during transmission or it could have come from a different protocol.
-
-To fix this issue, check that the client uses the RADIUS protocol. Also, ensure there are no software or hardware problems. Check that the client and server are communicating using the RADIUS protocol. To do this, check the packet capture or network traffic to confirm the packets being sent are properly formatted RADIUS packets.
+Fix the client to stop sending non-RADIUS traffic to the RADIUS
+server.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Attribute Header Overflows the Packet
-The server detected a serious issue with the structure of a received packet. The attribute header extends beyond the end of the packet, which is not valid. This occurs when the client sending the packet is broken or has an incorrect setup.
+This message indicates that the packet is likely not RADIUS. Or, it's
+a RADIUS packet which was somehow truncated and corrupted in the
+network.
-Another possibility is that the server didn't receive a valid RADIUS packet. The server can't process the packet as a RADIUS message because of this structural error(s). Review your configurations and verify the network's stability and congestion.
+Fix the client to stop sending non-RADIUS traffic to the RADIUS server.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Attribute has Invalid Length
-The server receives a network packet with an attribute that isn't the right length for the RADIUS protocol. The client sending the packet is broken and is sending invalid packets of the wrong size.
+The RADIUS packet is malformed, which means that it's not RADIUS.
-Also, the data the server receives may not be a valid RADIUS packet. These packets may be some other network traffic that is unrelated or corrupted. In either case, the server can't process the packet as a valid RADIUS message because the attribute length is incorrect.
+Fix the client to stop sending non-RADIUS traffic to the RADIUS
+server.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
The client is either completely broken, or the packet is not RADIUS.
-The server receives a network packet with an attribute that isn't the right length for the RADIUS protocol. The client sending the packet is broken and is sending invalid packets of the wrong size.
+The server receives a network packet with an attribute that isn't the
+right length for the RADIUS protocol. The client sending the packet is
+broken and is sending invalid packets of the wrong size.
-Also, the data the server receives may not be a valid RADIUS packet. These packets may be some other network traffic that is unrelated or corrupted. In either case, the server can't process the packet as a valid RADIUS message because the attribute length is incorrect.
+Update the client to stop sending non-RADIUS packets to the RADIUS
+server.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Failed binding to socket
-The FreeRADIUS server was unable to open a network socket on the specified port. The most common reason for this is that there's another FreeRADIUS instance running in the background.
+The FreeRADIUS server was unable to open a network socket on the
+specified port. The most common reason for this is that there's
+another FreeRADIUS instance running in the background.
-If you start the server in debug mode without stopping the current process, it can't bind to the port. To resolve this issue, stop any running FreeRADIUS server before you start it in debug mode.
+If you start the server in debug mode without stopping the current
+process, then the server port is already in use by the background
+process. The foreground process therefore cannot bind to the port.
+To resolve this issue, stop any running FreeRADIUS server before you
+start it in debug mode.
-Another possibility is that the server doesn't have the correct permissions (UID/GID) to open the socket. Security mechanisms like SeLinux can also block the server from accessing the port. To fix these issues, ensure the server has the correct permissions. Also, check your security settings to confirm that nothing is blocking socket access.
+Another possibility is that the server doesn't have the correct
+permissions (UID/GID) to open the socket. Security mechanisms like
+SeLinux can also block the server from accessing the port. To fix
+these issues, ensure the server has the correct permissions. Also,
+check your security settings to confirm that nothing is blocking the
+server from opening sockets on the configured IP address and port.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Failure Decoding the Packet
-The message "Failure Decoding the Packet" means that the server can't interpret a received network packet. This failure may be caused by one of the following:
+The message "Failure Decoding the Packet" means that the server cannot
+process a packet which it has received. This failure may be caused by
+one of the following:
-* The server has run out of memory, preventing it from processing the packet.
+* The server has run out of memory,
* There are malformed Vendor-Specific Attributes (VSAs) within the packet.
* The Type-Length-Value (TLV) is too deep.
* Unusual or unexpected packet structures cause packets to be malformed in some weird way.
-In all these cases, the server can't process the packet because its format is invalid or corrupt.
+In all these cases, the server discards the packet.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= IO Error
-Network or OS errors can happen due to hardware failures, network issues, or unexpected system behaviour. These factors make diagnosis and resolution difficult. For example, a company might experience frequent downtime from an unreliable internet provider. Similarly, a website may crash when traffic exceeds the server's capacity.
-
-A small mistake in the network settings can cause many errors which may cause more disruptions including system failure. Also, the lack of standardisation and interoperability between systems makes things difficult. It becomes hard to find and fix the root cause of errors.
-
-Administrators can reduce risks by taking these steps:
-
-* Invest in strong infrastructure.
-* Perform regular maintenance and updates.
-* Develop emergency and/or backup plans.
-
-These actions help minimise downtime and keep operations running smoothly.
-
-To identify the issue, you may need to review logs, check system resources, or talk to network administrators. Fixing network and OS errors requires careful troubleshooting and in-depth knowledge of the FreeRADIUS eco-system.
-
+An IO error usually indicates a temporary problem with the local
+operating system or network. For example, it can be due to
+permissions error, failure of a network interface, routing failure,
+etc. It should happen rarely.
+
+As the error here is due to the network or operating system, you
+generally cannot fix it by updating the server configuration. You
+will have to track down the source of the error, which is outside of
+the server.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Message-Authenticator is missing
-This error happens when the Message-Authenticator attribute is missing from the RADIUS packet. This attribute is used to check the integrity and authenticity of RADIUS messages. The Message-Authenticator stops malicious attacks. Without it, the server faces serious risks, like the BlastRADIUS attack. BlastRADIUS attacks happen when the Message-Authenticator is missing or used incorrectly. Unauthorised users gain access to network resources and services, putting the system's security and integrity at risk.
+This error happens when the Message-Authenticator attribute is missing
+from the packet. This attribute is used to check the integrity
+and authenticity of RADIUS messages.
-The Message-Authenticator attribute acts like a digital fingerprint for RADIUS messages. It verifies that the messages are genuine. Sending a packet without it is like not having a tracking number. It's difficult to check who sent it or what's inside. This error indicates a potential security risk when it appears. The packet may not be trustworthy or follow best practices. This highlights the urgency to fix the issue to prevent security breaches.
+The `Message-Authenticator` attribute acts like a digital signature
+for RADIUS messages. It verifies that the messages are
+genuine, and are from a genuine client.
+This error can stem from a misconfigured RADIUS client.
-This error can stem from a misconfigured RADIUS server or a faulty client. To resolve it and avoid future problems, understanding the cause is important.
+TBD: EAP requires Message-Authenticator, as does BlastRADIUS
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Header 'Length' does not match received packet length
-The RADIUS protocol defines a header with a 'Length' value to indicate the packet's size. The packet header's 'Length' field shows a size that does not match the actual packet size. If this value and the packet's actual size do not match, the packet is likely malformed or not a valid RADIUS packet.
+The RADIUS protocol defines a header with a 'Length' value to indicate
+the packet's size. The packet header's 'Length' field shows a size
+that does not match the actual packet size. If this value and the
+packet's actual size do not match, the packet is likely malformed or
+is not a valid RADIUS packet.
-Discrepancies can occur because of network errors, misconfigured clients, or malicious activity. To be safe, we recommend blocking the source IP address to prevent any issues or attacks.
+Discrepancies can occur because of clients sending non-RADIUS traffic
+to the RADIUS server, or possibly an attack. To be safe, we recommend
+blocking the source IP address to prevent any issues or attacks.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Did not find request which matches response
-The xref:reference:raddb/mods-available/radius.adoc[radius] module shows this error message when it sends packets. The issue may occur when the server:
+The xref:reference:raddb/mods-available/radius.adoc[radius] module
+shows this error message when it sends packets. The issue may occur
+when the server:
* Sent a request.
* Never received a response.
include::partial$secret_wrong.adoc[]
-If a packet fails verification, the server can't confirm if the packet is authentic, so the authentication process fails. The mismatch can happen during setup or password updates not being the same.
+If a packet fails verification, then the serce will refuse to process
+the packet. It could be a forgery, attack, or a misconfiguration/
-An example is when a network administrator sets up a RADIUS client with a shared secret. But they forget to update the server with the same secret. When the client tries to authenticate, the packet won't be verified, and authentication fails.
+An example is when a network administrator sets up a RADIUS client
+with a shared secret. But they forget to update the server with the
+same secret. When the client tries to authenticate, the packet won't
+be verified, and authentication fails.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Packet Too Large
-The "Packet Too Large" error occurs when a client sends a RADIUS packet with too much data. The RADIUS protocol limits packet size to 4k, ensuring reliable communication and interoperability between network devices. If a packet exceeds this limit, the server can't process it and reports an error.
+The "Packet Too Large" error occurs when a client sends a RADIUS
+packet with too much data. The RADIUS protocol limits packet size to
+4k. If a packet exceeds this limit, the server can't process it and
+reports an error.
-This error means that the client is broken/misconfigured. Either the client sends too much data or doesn't follow the protocol guidelines. To fix this, check the client's setup and make sure it meets the RADIUS packet size limits.
+This error means that the client is broken or is misconfigured. To
+fix the error, check the client's configuration and make sure that it
+is sending valid RADIUS packets.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Packet too small
-RADIUS packets must be at least 20 bytes in size. If you see this error, it means that non-RADIUS packets are being sent to the RADIUS port. Update your firewall rules to block traffic from that source IP.
+The RADIUS specifications say rhat packets must be at least 20 bytes
+in size. If you see this error, it means that non-RADIUS packets are
+being sent to the RADIUS port.
+
+Find the system which is sending the non-RADIUS traffic, and update it
+so that it does not send traffic to the RADIUS server. Or, add a
+firewall rule on the RADIUS server to block traffic from that source
+IP address.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Proxy-State is missing
+= Packet Proxy-State but no Message-Authenticator
-This error occurs when the Proxy-State attribute is missing from a RADIUS packet. The Proxy-State attribute is vital for servers to track and manage requests. Without it, servers struggle to manage requests, which impacts authentication and performance.
+This error occurs when the `Proxy-State` attribute is in an
+`Access-Request` packet, but the packet does not contain
+`Message-Authenticator`.
-A missing Proxy-State attribute can pose serious security risks, including the BlastRADIUS attack. This attack can cause a denial-of-service or allow unauthorised network access. Without the Proxy-State attribute, the server is more open to attacks.
-
-The Proxy-State attribute also stops replay attacks. An intruder intercepts a real request and then resends it, thereby gaining unauthorized access. By including this attribute in RADIUS packets, servers can process requests securely.
-
-The Proxy-State attribute is critical for maintaining network security. It ensures RADIUS systems remain secure and reliable, but it requires proper configuration and management to function effectively.
+TBD: Point to BlastRADIUS document and `limit_proxy_state`
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
include::partial$secret_wrong.adoc[]
-
-
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Too many attributes
-If you see an error about max_attributes, it usually means a client is sending too many attributes. It's probably due to a misconfigured client or a possible attack on the server. Either way, check what the client is doing before changing the configuration.
+This error means that the client is sending too much information in a
+packet. It is due either to a misconfigured client or a possible
+attack on the server. Either way, you should check what the client is
+sending via `tcpdump` or `wireshark`, before changing the
+server configuration.
-The default value for max_attributes is high enough for most common use cases. However, if you do increase this limit, be careful. It might make the server vulnerable to resource exhaustion attacks.
+The default value for `max_attributes` is high enough for most common
+use cases. However, if you do increase this limit, be careful. It
+might make the server vulnerable to resource exhaustion attacks.
-Each `listen` section has a `max_attributes` setting to limit the number of attributes that can be included in a single request. By enforcing this limit, the server protects itself from clients that might try to overload it. For example, malicious clients that consume large amounts of memory on the server for each request.
+Each `listen` section has a `max_attributes` setting to limit the
+number of attributes that can be included in a single request. By
+enforcing this limit, the server protects itself from clients that
+might try to overload it.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Unexpected Request Code
-This error occurs when a RADIUS server is set up incorrectly. The listen section specifies which RADIUS packets the server accepts on a port or interface. If a client sends a packet that does not match the configuration, the server rejects it and returns an "Unexpected Request Code" error.
-
-A key aspect of the RADIUS protocol is that it does not have a negotiation phase between the client and server. This is different from other protocols. For example, HTTP allows a client to send an OPTIONS request to check a server's capabilities. In contrast, a RADIUS client cannot discover which packet types a server will accept. This means someone has to manually adjust settings if there’s a mismatch. These issues cause admin problems. Many forum posts show challenges with RADIUS setups. Support requests also highlight these troubles. For instance, in a university, various departments may use different RADIUS clients. Making sure these clients work with the central RADIUS server can be complex.
-
-To fix an Unexpected Request Code error, you have two options. First, change the client to send only the expected packet types. This may involve updating the client’s software or adjusting its configuration files. This ensures the client works within the limits set by the server's listen section.
-
-You can also change the server's listen section to accept the packet types sent by the client. This may mean adding new sections or adjusting existing ones. This flexibility helps network admins configure the RADIUS server to fit their clients' needs. It ensures smooth communication and authentication.
-
-For example, adding a new listen section for a VPN service lets users access the network securely from remote locations. This does not disrupt existing authentication flows. By fixing the Unexpected Request Code issue, admins can build stronger RADIUS configurations. This improves network security and reliability.
-
-
+This error occurs when the RADIUS client and server do not have a
+common configuration. Each listen section specifies which RADIUS
+requests that the server accepts. If a client sends a request which is
+not listed in the `listen` section configuration, the server will
+reject it and show an "Unexpected Request Code" error.
+
+A key aspect of the RADIUS protocol is that it does not have any way
+to negotiation capabilities between the client and server. This is
+different from many other protocols. For example, HTTP allows a client
+to send an OPTIONS request to check a server's capabilities. In
+contrast, a RADIUS client cannot discover which packet types a server
+will accept. This means that an administrator has to manually update
+the configuration if there’s a mismatch.
+
+To fix an Unexpected Request Code error, you have two options. First,
+reconfigure the client to send only the packet types that the server
+expects. This may involve updating the client’s software or adjusting
+its configuration files. This ensures the client works within the
+limits set by the server's listen section.
+
+You can also change the server's `listen` section to list the packet
+types sent by the client. See the individual `listen` section for how
+this is done.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Unexpected response code
-Each request sent has only a few valid responses that can be processed successfully. The next hop, such as a server or device, can send a bad or wrong response. When sending a request within a network protocol, only a limited set of responses is expected from the recipient. The invalid or incorrect response may be due to misconfiguration, software bugs, or unexpected network behavior.
+Each request sent has only a few valid responses that can be processed
+successfully. The next hop, such as a proxy or home network can,
+however send anything in the response. This capability means that
+it's possible for the next hop to send (for example) a
+`Accounting-Response` reply the local server sent an `Access-Request`.
-Receiving a bad or wrong response can disrupt normal operations and may need troubleshooting to find the cause and ensure systems communicate properly.
+The invalid or incorrect response may be due to misconfiguration, or
+software bugs. The problem is caused by the next hop server which is
+sending the bad response, not by the local server which is received it.
+
+Receiving a bad or wrong response will cause the server to ignore the
+response, as no valid response was received. The solution is to
+contact the administrator of the next hop server, and ask them to
+correct the issue.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Unknown Packet Code
-This error occurs when the network processes RADIUS packets as part of the user authentication process. Each RADIUS packet has a "code" field that defines its type, like Access-Request or Access-Accept. The Internet Engineering Task Force (IETF) specifies valid codes in their documents. These codes must be between 1 and 53. Any code outside this range, such as 0 or above 53, is invalid and cannot be processed.
+This error occurs when the network receives a RADIUS packet which is
+not defined by the standards. Each RADIUS packet has a "code" field
+that defines its type, like `Access-Request` or `Access-Accept`. The
+Internet Engineering Task Force (IETF) specifies valid codes in their
+documents. These codes must be between 1 and 53. Any code outside this
+range, such as 0 or above 53, is invalid and cannot be processed.
-When an invalid code appears, it usually means two things. First, the device or client sending the packet may not follow RADIUS rules. This can result in bad packets. It might happen if the manufacturer didn’t implement the protocol correctly or due to a software bug. For instance, a mistake in their RADIUS setup could lead to invalid codes.
+When an invalid code appears, it usually means two things. First, the
+device or client sending the packet is not following the RADIUS
+standards. Perhaps the manufacturer didn’t implement the protocol
+correctly, or has a bug in their software.
-Second, the error might show that traffic not meant for RADIUS is sent to the RADIUS port. This often happens because of a misconfigured network or device. A network administrator may have set up a device to send extra traffic to the RADIUS port. This can overwhelm the server with bad packets.
+Second, the error might show that traffic not meant for RADIUS is sent
+to the RADIUS port. This often happens because of a misconfigured
+network or device. A network administrator may have set up a device to
+send non-RADIUS traffic to the RADIUS port. These packets will cause
+the server to complain.
-In both cases, the server cannot process the packet. This leads to authentication failures and potential network issues. To fix this, network administrators need to find the source of the problem, whether it's a faulty client or misconfigured settings. They must ensure only valid RADIUS packets reach the server. This may involve updating software, adjusting network settings, or blocking non-RADIUS traffic. By fixing the Unknown Packet Code error, administrators can stabilize the network and prevent future authentication issues.
+In both cases, the server cannot process the packet. To fix this,
+network administrators need to find the source of the problem, whether
+it's a faulty client or misconfigured settings. They must ensure only
+valid RADIUS packets reach the server. This may involve updating
+software, adjusting network settings, or blocking non-RADIUS
+traffic. By fixing the Unknown Packet Code error, administrators can
+stabilize the network and prevent future problems.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-The shared secret is wrong. Fix it! RADIUS uses a shared secret, a key security feature, to ensure that communications are secure across the network and devices. This is a password or key known only to the client and server.
+The shared secret is wrong. Fix it! RADIUS uses a shared secret, a key
+security feature, to ensure that communications are secure across the
+network and devices. This is a password or key known only to the
+client and server.
-If you see this message, it means the shared secret on the client and server don’t match. To resolve this issue, check that the shared secret is identical on both the client and server.
+If you see this message, it means the shared secret on the client and
+server don’t match. To resolve this issue, check that the shared
+secret is identical on both the client and server. In many cases, you
+should just re-enter the shared secret on both sides.
projects / thirdparty / freeradius-server.git / commitdiff
