Transceiver compatibility codes: why a module is rejected and how to fix it
A switch rejects a transceiver for one of three reasons: the EEPROM identity fields do not match the platform allow-list, the software policy refuses a foreign part code, or the port configuration and module cannot agree on speed, FEC or application. The trace differs in each case, and so does the fix.
Why does a switch reject a module that physically fits?
SFF-8431 gives SFP+ its cage, connector and electrical interface; SFF-8636 does the same job for QSFP and QSFP28; QSFP-DD and OSFP modules follow the OIF CMIS management model. None of them tells the host what is plugged in. That comes from a two-wire EEPROM at I2C address A0h — read before the transmitter is enabled.
Nothing in the cage reports a manufacturer. The insert-detect pin says only that something is present.
What the host does with the read is software, decided per platform model and per software release. Cisco publishes a transceiver compatibility matrix for each switch family and NOS release; a part listed for one release can be missing from the next, and a part listed for a 48-port line card is not automatically listed for a 32-port chassis of the same family.
The EEPROM read also fails in ways that look like rejection. A dirty management-pin contact, a bent cage pin, or a module still in its power-up sequence can return 0xFF on every byte; the host reports an unknown module and holds the port down. Reseating and re-reading the identity fields separates a bus fault from a policy refusal.
What does a compatibility code hold inside the EEPROM?
SFF-8472 lays out the 256-byte A0h page: bytes 0–62 the identification block, byte 63 a checksum over it, bytes 64–94 the options and diagnostic declarations, byte 95 a second checksum, bytes 96–127 vendor-specific.
| Byte(s) | Field (SFF-8472 A0h) | What the host does with it |
|---|---|---|
| 0 | Identifier | Memory map; 0x03 declares SFP/SFP+/SFP28 (SFF-8024) |
| 1 | Extended identifier | Extra identifier detail per SFF-8024 |
| 2 | Connector type | LC, MPO or copper |
| 3–10 | Compliance codes | The optical and electrical standard (10GBASE-LR, 1000BASE-SX) |
| 11 | Encoding | NRZ or 64B/66B |
| 12 | Nominal bit rate | 100 MBd units; 103 for 10.3125 Gb/s |
| 14–18 | Link length by fibre type | Reach in km, 100 m and 1 m units |
| 20–35 | Vendor name | 16 ASCII bytes; the string a policy check matches |
| 37–39 | Vendor OUI | 3 bytes |
| 40–55 | Vendor part number | 16 ASCII bytes; the code an allow-list matches |
| 56–59 | Vendor revision | 4 ASCII bytes |
| 60–61 | Wavelength | nm, 16-bit |
| 63 | CC_BASE | Checksum over 0–62 |
| 64–65 | Options | TX disable, TX fault, LOS |
| 66–67 | Bit rate max/min | Rate envelope |
| 68–83 | Vendor serial number | 16 ASCII bytes |
| 84–91 | Date code | YYMMDD plus two lot bytes |
| 92–94 | Diagnostic type, enhanced options, compliance | DDM support and revision |
| 95 | CC_EXT | Checksum over 64–94 |
| 96–127 | Vendor specific | OEM codes and private fields |
Bytes 3–10 declare what the module is optically: a 100GBASE-LR4 part carries the same compliance bits whoever builds it, because IEEE 802.3ba defines four 25.78 Gb/s lanes at 1295.56, 1300.05, 1304.58 and 1309.14 nm over 10 km. Bytes 40–55 carry the vendor’s part number, and that string is what the platform list matches. A Huawei 02311QDH record in the 100G QSFP28 catalogue shows the split: 100GBASE-CWDM4, 4×25G, 1310 nm, 2 km, LC/PC, optical values −6.5 / 2.5 / −9.8 dBm; the optics meet the CWDM4 MSA of 2014 and 02311QDH is Huawei’s code for them.
The checksums are the part buyers miss. CC_BASE at byte 63 is the sum of bytes 0–62 modulo 256, CC_EXT at byte 95 the same for 64–94 (SFF-8472). Recoding rewrites those bytes and changes the sum. A recoded module with a stale checksum fails on the first read: Cisco platforms log a GBIC_SECURITY_CRYPT-4-VN_DATA_CRC_ERROR-class message and keep the port down, and the vendor string is never compared because the block never parsed.
Why does a CMIS module stay dark with no fault logged?
Above 25G the map changes shape. QSFP parts use the SFF-8636 lower page with upper pages behind a page-select byte; QSFP-DD, OSFP and most 400G parts use OIF CMIS, which adds a module state machine (ModuleLowPwr, ModulePwrUp, ModuleReady, ModuleFault), per-lane data path states, and application descriptors the host selects with an AppSel code. A healthy CMIS module can sit in ModuleReady with every data path deactivated because the host never wrote the selection.
The three rejection layers
Identity, policy and capability all end in a port that will not come up, and each needs a different repair.
Identity failures sit in the block itself: a checksum mismatch, an all-0xFF read, a part number absent from the matrix. Policy failures parse cleanly and are refused by an allow-list keyed to platform model and NOS release, the only layer where some vendors ship a documented override. Capability failures are accepted modules whose port stays down over speed, FEC, breakout or the application table.
| What the port shows | Layer | First check | Usual fix |
|---|---|---|---|
| err-disabled, syslog names gbic-invalid | Identity or policy | EEPROM fields against shell print and matrix | Correct code, or documented override |
| down, module listed as unsupported | Policy | Matrix entry for this model and release | Override, newer NOS, coded part |
| identity fields blank, zero or 0xFF | Identity | Reseat, second port, known-good module | Replace module or cage |
| up, FEC-uncorrected counter climbing | Capability | FEC mode at both ends | Match RS-FEC or FC-FEC |
| module ready, no lane trained | Capability | Speed, breakout, AppSel | Port config or a different application |
| up at a quarter of the expected rate | Capability | Lane count and breakout profile | Apply the breakout profile |
Replacing a module refused by an allow-list wastes a part: a new one of the same part number will be refused the same way. The reverse error costs more time: a port that accepts the module and then fails to train gets diagnosed as policy when the speed or FEC setting is the fault.
How do Cisco, Aruba, Huawei and Juniper each handle a foreign module?
Every platform here reads the same A0h block. What differs is how much the software parses, what the refusal looks like, and whether a switch-wide lever exists.
| Host family | Command that reads the module | Output worth capturing | Lever when the module is refused |
|---|---|---|---|
| Cisco IOS-XE | show interfaces transceiver detail |
Vendor, part number, serial, date code, five DDM values; show interfaces status err-disabled names the cause |
service unsupported-transceiver, plus err-disable controls |
| Cisco NX-OS | show interface transceiver details |
Same identity block, per port | service unsupported-transceiver |
| Huawei VRP | display transceiver interface verbose; display transceiver diagnosis interface |
Vendor, part, date code; TX and RX power, bias, voltage, temperature | A module carrying Huawei’s part code |
| Juniper Junos | show interfaces diagnostics optics; show chassis hardware |
Per-lane TX and RX power with alarm flags; inventory listing | A Juniper-qualified part code |
| ArubaOS-Switch | show interfaces transceiver |
Per-port module type and status | allow-unsupported-transceiver |
| Arista EOS | show interfaces transceiver |
Manufacturer, model, serial, revision per port | An Arista-qualified part code |
The Cisco IOS-XE override is a global command, an err-disable control and a port bounce. service unsupported-transceiver in global configuration suppresses the part-number check; where the port still err-disables, no errdisable detect cause gbic-invalid removes the trigger; errdisable recovery cause gbic-invalid turns on automatic recovery, off by default and running on a 300-second interval. The port then needs shutdown and no shutdown, because an err-disabled port does not retest the module on its own.
Cisco’s err-disable cause is the literal string gbic-invalid, even on an SFP+ or QSFP28 port, because the identifier dates from the GBIC era; searching a log for “transceiver” on IOS-XE can miss the event, while gbic-invalid finds it.
Huawei VRP takes the other route: the lever is the module’s code, reported through display transceiver interface verbose. Juniper and Arista expose per-lane diagnostics through their own commands, and the lever there is the part code.
ArubaOS-Switch carries the other documented switch-wide control: allow-unsupported-transceiver relaxes the check for modules outside the supported list.
Configuration faults that look like rejections
Before a module is condemned, check the port’s speed, FEC, breakout and application settings; each fault produces a port that looks refused.
Speed is the first check: a 100G QSFP28 module in a port nailed to 40G never trains, because 100GBASE-SR4 carries four lanes at 25.78125 Gb/s over 850 nm to 70 m on OM3 and 100 m on OM4 (IEEE 802.3bm), while 40GBASE-SR4 carries four at 10.3125 Gb/s to 100 m on OM3 and 150 m on OM4 (IEEE 802.3ba). The cage accepts both; the speed setting does not.
FEC is second and is the classic false rejection on 100G. IEEE 802.3bj Clause 91 defines RS(528,514) for 100GBASE-CR4 and KR4, and both ends must agree. A port set to fec rs facing a peer set to fc or off stays down with healthy DDM values, because the module is healthy and the negotiation never completes. The same failure appears on 25G links when one end requests RS-FEC and the other does not (IEEE 802.3by).
The third check is breakout, the setting most often left at its default. A 100G port fitted with a 4×25G module produces four 25G links only after the breakout profile is applied, and on many platforms that profile is assigned at port-group level, which requires the other ports in the group to be shut first. Without it, one lane trains and three stay dark.
The CMIS application table is fourth and only appears above 100G. A 400G module advertises the applications it supports, each with a host interface, media interface and lane count, and the host writes an AppSel code to pick one. A module listing 400GBASE-FR8 as eight 50G lanes will not satisfy a port configured for four 100G lanes, though both describe 400G.
A swap test settles the split between hardware and configuration faster than any log reading. Move the module to a second port of the same type with the same speed and FEC settings; if it trains there, the first port’s configuration or cage is the fault, and if it fails in two ports and a second chassis, the module is the fault.
How do you clear a rejected port, in order?
- Capture the state before touching the module: the syslog line,
show interfaces status err-disabled,show interfaces transceiver detail. A reseat before the capture destroys the evidence. - Read the identity fields against the shell print and the platform matrix. The EEPROM verification guide covers the field-by-field comparison when the three sources disagree.
- Decide whether the block parsed. A checksum failure or an all-0xFF read ends the diagnosis: the module is corrupt, wrongly recoded, or not making contact.
- If the block parsed and the part is absent from the matrix, the layer is policy: apply the documented override or obtain a correctly coded module.
- On IOS-XE:
service unsupported-transceiver,no errdisable detect cause gbic-invalidwhere the trigger persists,errdisable recovery cause gbic-invalidfor automatic recovery. Thenshutdownandno shutdown. - If the module is accepted and the link still fails, work the capability layer one setting at a time: speed, FEC, breakout, AppSel. A FEC change and a speed change made together cannot be told apart afterwards.
- Compare DDM against the datasheet for that exact part. The Cisco SFP-10G-LR datasheet gives −8.2 to +0.5 dBm transmit and a 0–70 °C case range; a unit outside those numbers at room temperature is failing, and a unit reporting identical RX power with the fibre removed is not measuring.
service unsupported-transceiver leaves a residue: it is global, it relaxes the check for every port in the chassis, and it stays in the configuration after the module that prompted it is gone. Recoding a module on site is a data write with a checksum attached, and a write that skips the recompute moves the failure from unsupported to corrupt.
When should the module go back to the supplier?
A module refused by policy has no technical defect, and an RMA raised on that basis wastes a shipment cycle.
A checksum failure on a module nobody recoded. CC_BASE at byte 63 and CC_EXT at byte 95 are sums over fixed ranges (SFF-8472); a new module that fails either is corrupt or misdescribed.
Shell print against EEPROM. Vendor name at bytes 20–35 and part number at bytes 40–55 should match the label; a mismatch means relabelled or recoded hardware.
A wavelength that contradicts the part. Bytes 60–61 are in nm, and an LR shell over an 850 nm block will not link on single-mode at any setting.
DDM outside the datasheet at the start of life. The Cisco SFP-10G-LR transmit window of −8.2 to +0.5 dBm and the 0–70 °C case range are datasheet limits; a unit below the window at 25 °C ambient has no margin for a hot rack. The 10G SFP+ guide works the same budget arithmetic for 1310 nm links.
Static diagnostics. If RX power reads the same with the fibre connected and disconnected, the number is a stored constant rather than a measurement.
A date code months newer than the shell print. SFF-8472 stores YYMMDD at bytes 84–89, and a gap of months points to rework or a replaced shell.
Reach class is a separate question from defect. A 100GBASE-CWDM4 module is specified to 2 km (CWDM4 MSA, 2014) and a 9 km span needs the LR4 part at 10 km (IEEE 802.3ba); the short-reach module works as designed and sits in the wrong link. The CWDM4 versus DWDM metro guide sets out the wavelength-grid side of that choice.
Purchase-order fields that prevent rejection
A line reading “100G QSFP28 LR4, quantity 20” leaves acceptance to whoever packs the box.
Platform and software release. The matrix entry is per model and per release, so the model number and NOS version belong on the order.
Coding family and exact code. The code is what the platform matches: SFP-10G-LR for a Cisco 10G port, GLC-LH-SMD for a 1G port, JNP-QSFP-100G-LR4 for a Juniper 100G port, 02311QDH or 023123WA for the Huawei OSN environment. The 25G and 100G module guide maps the families port by port, including the 25G split.
Port speed, FEC and breakout plan. A 100G port that will run 4×25G needs a module whose application table matches, and a port that will run RS-FEC needs a module that supports it.
Fibre type and reach. OM3, OM4, G.652, LC or MPO, and the measured path length. The 2 km CWDM4 class and the 10 km LR4 class are different products, and the 25G SFP28 catalogue shows the same split at 25G.
A per-unit coding statement. Which platform family the module is coded for, in writing, with the part code the EEPROM will report.
Condition and test record. New, refurbished or used, and what the test covered. Spares bought later should carry the same code as the installed base, because a mixed-code estate doubles the spare count. Each record in the equipment catalogue states the condition of the unit.
Frequently asked questions
Can a module coded for one switch vendor be recoded for another, and does the optical performance change? The identity block is writable on many third-party modules, so bytes 20–35 and 40–55 can be rewritten, and CC_BASE at byte 63 and CC_EXT at byte 95 have to be recomputed (SFF-8472). The laser, receiver and driver are untouched, so the optics stay what they were. What changes is the claim: the vendor string no longer describes the hardware, and a platform that also compares the OUI at bytes 37–39 or the date code will refuse the module on the second look.
Why does a module work in one port and fail in the port beside it? Ports are not identical inside one chassis. QSFP+ and QSFP28 cages share a footprint, but a port built for 40G may never run a 100G module, and ports in one group often share a rate, so a 100G setting on one can disable or re-rate its neighbours.
Does a software upgrade change which modules are accepted? The allow-list travels with the NOS image, and vendor matrices are published per platform and per release. A module accepted on one release can be missing from the next, so qualification is release-specific and the image version belongs beside the part code in the asset record.
Are direct-attach copper cables checked the same way? Yes. An SFP+ passive copper cable carries the same A0h identity block, with the copper length in byte 18 in units of 1 m and a compliance code declaring the cable type (SFF-8472). QSFP copper assemblies carry an SFF-8636 page instead. A “cable not supported” event usually comes from the same allow-list that refuses optics.
Will a 1G SFP module work in a 10G SFP+ port? The cage accepts it and the identity read is the same 256-byte block, but the port has to support 1000BASE-X and be set to 1000 Mb/s. The module declares 1.25 Gb/s as a nominal bit rate of 13 in byte 12, and a port that only runs 10.3125 Gb/s will report an unsupported rate even when the module itself is working.
What does an all-zero diagnostic block mean? It means the A2h page returned no data; a module sitting at 0 dBm would still report a live bias current. Common causes are a module held in low-power state (CMIS ModuleLowPwr), a management-bus contact fault, or a host that has not started diagnostics. A live laser with zero reported bias is a diagnostics failure, while zeros across every field point at the bus.
Need a specific part?
Send the part number and quantity — we confirm condition, availability and price before you commit.