Troubleshooting

The link won't come up at all

1. Confirm the module is fully seated

Switch# show interface tengigabitEthernet 1/0/49 transceiver detail

If the output says transceiver is not present but you can see the module in the cage, it's not fully seated. Re-seat firmly.

2. Confirm the port is administratively up

Sounds obvious. Check it anyway, show running-config interface <X> for shutdown, or show interfaces et-0/0/0 extensive for Admin: Down.

3. Confirm both ends have compatible optics

Same wavelength, same fiber type, same reach class. An SR talking to an LR will not link up: different wavelengths, different fiber types.

4. Confirm the module is enabled by the host

Switch# show interface tengigabitEthernet 1/0/49 transceiver detail | include status

Look for Vendor Name. If it's blank or shows "UNKNOWN", the switch didn't enable the module. On Cisco platforms, this means either the module is mis-coded for this platform, open an RMA, we'll re-code it, or the switch firmware was updated and rejects the previous coding.

5. Clean the fiber connectors

Inspect both connectors with a fiber scope. If either is dirty, click-clean and re-inspect. The single most common cause of "the link won't come up" after a new install is a contaminated end-face from manufacturing residue or installation handling.

6. Confirm fiber polarity

For duplex LC: the Tx of one module must connect to the Rx of the other. Modern LC duplex cables are pre-paired and keyed, so this is rare, but loose pigtails and broken-out trunks can be reversed. For MPO trunks: confirm the polarity (Type A, B, or C). A polarity mismatch will not link up.

7. Check the receive power

Switch# show interface tengigabitEthernet 1/0/49 transceiver detail | include Rx
Optical Lane Rx Power:
  Lane 1: -18.7 dBm

If Rx power is below the module's receiver sensitivity, the link can't decode the signal. Possible causes: fiber too long for the module's reach class, excessive connector loss, or a dirty/scratched connector somewhere in the path.

8. Check the transmit power on the other end

Receive on this end = transmit on the other end, minus fiber loss. If your local Rx is low, log into the remote switch and check the remote Tx.

remote-switch# show interface tengigabitEthernet 2/0/49 transceiver detail | include Tx

9. Try a known-good module on the same port

Pull the suspect module. Insert a known-good module (same type, same coding). Does it link up?

• Yes → original module is faulty. Open an RMA.
• No → port or fiber issue. Try the suspect module in a different port on the same chassis.

This A/B/A test isolates the failure to module, port, or fiber.

The link comes up but flaps

1. Capture DDM telemetry over time

Poll Tx/Rx power at 1-minute intervals for 15 minutes. Look for swings > 1 dB or periodic dips correlated with the flap timing.

2. Check for autoneg mismatch

For 1G fiber and copper SFPs, autoneg behavior must match end-to-end. If one end forces 1G full-duplex and the other auto-negotiates, you'll see intermittent renegotiation.

3. Check FEC settings (25G and above)

For 25GBASE-SR/LR and many 100G/400G/800G modules, Forward Error Correction is required. FEC defaults vary by platform:

• Cisco NX-OS 25G: defaults to RS-FEC on most line cards; some require explicit fec rs-fec
• Arista EOS 25G: usually defaults to RS-FEC
• Juniper Junos 25G: requires explicit set interfaces et-0/0/x ether-options fec rs-fec
• 800G OSFP: uses RS-FEC(544,514), coherent DSP modules (ZR/ZR+) implement their own FEC layer

4. Check for temperature issues

Switch# show interface tengigabitEthernet 1/0/49 transceiver detail | include Temperature
Module Temperature: 76.5 C

Above the alarm threshold (typically 70°C commercial, 85°C industrial), the laser auto-attenuates and the link drops. Causes: chassis airflow blocked, datacenter cooling event, or high-power modules (ZR, coherent) operating without adequate thermal margin.

5. Check for power instability

Supply voltage outside the 3.13–3.46 V band can flap the module. If voltage is consistently at the edges, the chassis PSU may be loaded near its limit or a bus connection may be intermittent.

The link is up but throwing CRC errors

1. Confirm clean fiber

Dirty or scratched connectors cause subtle signal distortion that passes link state but corrupts frames. Click-clean and inspect both end-faces.

2. Check Rx power vs. receiver sensitivity

A link that's within 1 dB of receiver sensitivity will pass link up but flake on real traffic. You want at least 2–3 dB of margin.

3. Check for FEC mismatch (25G+)

CRC errors with the link otherwise stable is a classic FEC mismatch symptom. See above.

4. Check duplex

Half-duplex on a fiber link in 2026 is unusual but not impossible on legacy gear.

5. Check for chromatic dispersion (long-reach modules)

For ZR and DWDM modules over 40+ km, chromatic dispersion can degrade the signal even on clean fiber. The fix is either a dispersion-compensating module (DCM) in the path or a coherent transceiver (built-in DSP-based compensation).

The link goes down at the same time every day

Almost always temperature-correlated. Check chassis temperature trend over 24 hours, datacenter cooling schedule, and heating/cooling loads on adjacent equipment.

The module shows up as "UNKNOWN" or won't enable

You have one of three problems:

1. Module mis-coded for this platform. Open a free vendor exchange, we re-code at no charge.
2. Switch firmware changed and is now rejecting the previously-valid coding. Email connect@netapi.io with the platform, firmware version, and module SKU. We'll send a coding update.
3. EEPROM damage from ESD or physical shock. Open an RMA for advance replacement.

When to open an RMA

Don't open an RMA for:

• A link that won't come up but you haven't yet swapped in a known-good module to isolate the cause
• Connector dirt, clean first
• Compatibility-program eligible swaps (different reach, different vendor coding) are a free exchange, not an RMA

Getting help

If you've worked through the relevant section and you're still stuck, email connect@netapi.io with:

• The NetAPI order number and module SKU
• The switch platform and OS version
• The full output of show interface ... transceiver detail (or platform equivalent)
• A description of what's failing and what you've already tried

A network engineer will reply within one business hour during business hours, or within four hours after-hours.