Troubleshooting#

“Have you tried turning it off and on again?” - The IT Crowd

Please refer to the table below for common issues and their potential solutions for Qblox Cluster.

Important

A list of what status the LED indicates can be found in the Cluster and DC Cluster user guides.

Frequently asked questions

We also have frequently asked question (FAQ) lists for Qblox architecture, qblox-instruments and Qblox scheduler.

In case your problem is not listed or you are unable to resolve it, kindly contact us through the designated Slack support channel. If there is a problem accessing Slack, you could use support@qblox.com to reach us.

Starting Troubles#

Problem	Solutions
The status (S) LED is not green or white.	If the LED is red, it indicates an error that needs to be resolved. Query `get_system_status()` to see what the problem is. If the LED is orange, it indicates a critical warning that an error has occurred but has been resolved. Query `get_system_status()` to see what the problem is. If the LED is yellow, the device is booting. If this state persists for more than 2 minutes, try power-cycling the device manually. At most two power cycles should be needed to boot the device.
The reference clock (R) LED is not green.	If the LED is red, no reference clock is found. Most likely you have selected the external input as reference source, but have not connected the reference. If the LED is blue, the internal reference clock is selected. Use the parameter `reference_source()` to change this if necessary.
The channel (I/O) LEDs are not green.	If the LED is red, an error has occurred in one or more of the connected sequencers. Query `get_sequencer_status()` to see what the problem is. If the LED is purple or blue, one or more of the connected sequencers are armed or running. Query `get_sequencer_status()` to see what the sequencers are doing. If the LED is orange, one or more of the connected sequencers are causing the output to clip. Query `get_sequencer_status()` to see what the sequencers are doing.
I cannot connect to the instrument.	Make sure that the Ethernet cables are firmly inserted into the instrument and host PC (see section Connecting to a single system). Make sure that the instrument and host PC are within the same subnet of the same network (see section Network configuration). Make sure that you are using the IP address of the instrument. If you do not know the IP address or are not sure you are using the correct one, see section Finding the IP address of a Cluster. If all else fails: 1. connect to the instrument with your computer directly, and disconnect everything else (WiFi etc. too), to make sure you’re really only connected to the offending device; 2. set your IP address to `192.168.0.200`, with netmask `255.255.255.0` (see section Finding the IP address of a Cluster); 3. run `qblox-pnp recover-device`; 4. the device should now reboot (if it doesn’t come back up within 1-2 minutes, remove and then reapply power); 5. you should now be able to connect to the instrument via its default IP address, namely `192.168.0.2`.
When I connect to the instrument, I got an error `[WinError x] No connection could be made because the target machine actively refused it`.	If at the same time, you are still able to find the cluster with `qblox-pnp list` under the IP `192.168.0.X`, but cannot connect to it, it is likely there is another instrument in your local network which has the same IP and thus clashes with the cluster during the connection. To verify that, power off the cluster and try to `ping 192.168.0.X` in the terminal to check whether you get a response. If that was indeed the case, turn the cluster back on and use `qblox-cfg 192.168.0.X set-ip <new-ip-address>` to change the IP address of the cluster, and then try to reconnect.
When I connect to the instrument, I get an error that the driver and firmware are incompatible.	This indicates that the version of your installed Qblox instruments package and the firmware of the instrument you are trying to connect to is not compatible. See the updating page for how to upgrade the firmware. If all else fails, the instrument can be instantiated in debug mode where this error is bypassed. However, this is highly discouraged and no guarantees can be given that the instruments will function properly.
When I connect a reference clock to REFⁱⁿ and configure the instrument to use an external reference clock, the reference clock LED (R) turns red.	Ensure that the reference clock source is outputting the clock as a 10 MHz, 1 Vpp signal. The REF^out from another Qblox instrument can be used for this as a test, but daisy-chaining Clusters is discouraged (see section Synchronization).
I cannot get the SYNQ to work.	Make sure that the SYNQ is enabled by setting the `Sequencer.sync_en()` parameter. Make sure that the sequencers are used to play waveforms and start acquisitions and that these sequencers are running the `wait_sync` instruction (see section Q1 Sequence Processor). When using multiple clusters: - Make sure that you are using a USB-C compliant cable to connect the instruments using the SYNQ connectors (see section Mainframe & CMM). - Make sure that the SYNQ cables are firmly inserted into the instrument. A distinct click should be felt when inserting them into the instruments.
I cannot get the trigger to work.	Make sure the trigger source is connected to the TRIGⁱⁿ SMP connector (see section Mainframe & CMM). Make sure that the trigger source is outputting a trigger. This can be easily verified using an oscilloscope. Make sure that the sequencers are used to play waveforms and start acquisitions and that these sequencers are running the `wait_trigger` instruction (see section Instructions).
The output voltage of the instrument is twice as high as expected.	Make sure that you terminate the output signal with 50 Ω.
I updated the firmware or IP address using the Qblox Configuration Manager and the LEDs turned yellow.	This is normal behavior and indicates that the instrument has stopped its internal processes and is trying to reboot (see updating). The process should be finished within 2 minutes.

Experiments and Measurements#

Issues	Troubleshooting Steps
No QCM-RF/QRM-RF Output on Scope (Or Gibberish Output)	1. Ensure LO is powered ON. 2. Enable modulation (`mod_en_awg()` = True) and set NCO frequency > 10 MHz (since IF path is AC coupled to the upconverting mixer). 3. Verify ON status of output RF switches (`marker_ovr_en()` or `set_mrk` Q1ASM commands). Refer to marker output channels for more info.
Cannot run Basic Sequencing/ Advanced Sequencing/ Acquisition / Multiplexed Sequencing Tutorial on RF modules	Please try the steps outlined in the previous question.
Binned Data Contains NaN	1. Ensure sufficient sequence wait time (`get_sequencer_status()` and `get_acquisition_status()`). 2. Make sure you are retrieving acquisitions from the correct index key. 3. Ensure that the Q1ASM program is populating all the bins as specified in the `num_bins` key of the acquisition dictionary.
Unexpected Q1ASM Results	1. Insert `nop` between consecutive commands on the same register. 2. Make sure your classical/parameter instructions are updated using `upd_param` or `play` or `acquire` commands.
Stuck Sequencers (Blue LEDs)	1. Verify proper `wait_sync` command placement. 2. Review `sync_en` settings for unused sequencers.
Output Amplitude Mismatch on Scope	1. Verify impedance compatibility (module output impedance = 50 Ohms) with oscilloscope input impedance. 2. Check your gain/offset values specified in the Q1ASM (if any) and make sure the values set are proportionally adjusted for the dynamic range of the module’s output DAC. `set_awg_offs 32767, 32767` will set a 2.5V DC offset on QCM (dynamic range 5Vpp) and 1V offset on QRM). 3. Check your gain/attenuation settings. 4. If modulation is ON, the output signal amplitude is smaller by a factor of \( \frac{1}{\sqrt{2}} \). Please check the NCO Control Tutorial for more info.
Oscillations on Frequency Sweep	1. Firmware ≤ 0.5.0: Oscillations of 6-7 MHz/oscillation may stem from fixed quantization noise during phase acquisition. We strongly recommend updating the firmware. If this is not possible, the oscillations can be reduced by enabling phase compensation with `nco_prop_delay_comp_en()`. 2. Oscillations at NCO frequency with decaying oscillation amplitude: Likely due to input ADC offsets (which get demodulated and integrated by the hardware). Please refer to the Binned Acquisition tutorial (last section) to see how one can calibrate away these offsets. 3. Oscillations can also be caused by other tones (e.g. multiplexed readout or input ADC offsets). If the phase of readout pulses is not fixed, the integrated magnitude of these spurious tones will depend on the frequency (as the phase of these tones at the start of integration depends on the frequency). This will contribute to an oscillating noise on top of the signal. You can use `set_ph` or `reset_ph` to eliminate this effect.
DC Offset on Scope Acquisition	1. Due to thermal/manufacturing effects ADC may show a small DC offset on top of your sampled signals. Please refer to the Characterizing Input Offset tutorial to see how one can calibrate away these offsets. 2. For RF modules, spurious tones at the frequency of oscillator (LO) can give rise to these offsets. You can use the calibration routine mentioned in the above point to get rid of these offsets. See also the RF version of the tutorial.
`get_sequencer_status()` returns a FLAG	1. `DISARMED`: Sequencer was disarmed. Note that the sequencer must be armed before start. 2. `FORCED_STOP`: Sequencer was stopped while still running. 3. `SEQUENCE_PROCESSOR_Q1_ILLEGAL_INSTRUCTION`: Classical/Q1 sequencer executed an illegal instruction. This error usually occurs if there is a `stop` instruction missing at the end of your sequence program. 4. `SEQUENCE_PROCESSOR_RT_EXEC_ILLEGAL_INSTRUCTION`: Real-time processor executed an illegal instruction. 5. `SEQUENCE_PROCESSOR_RT_EXEC_COMMAND_UNDERFLOW`: Real-time processor command queue underflow. This error occurs when the processing time of the Q1 instructions has exceeded the current wall-time of the experiment. This causes the execution of the next real-time instruction to be triggered without it having been filled into the real-time instruction buffer. See the FAQ for more details. 6. `AWG_WAVE_PLAYBACK_INDEX_INVALID_PATH_0`: AWG path 0 tried to play an unknown waveform. Please ensure that the indices referenced in your waveform dictionary for the sequence aligns with the ones specified in your Q1ASM program. 7. `AWG_WAVE_PLAYBACK_INDEX_INVALID_PATH_1`: AWG path 1 tried to play an unknown waveform… 8. `ACQ_WEIGHT_PLAYBACK_INDEX_INVALID_PATH_0`: Acquisition path 0 tried to integrate with an unknown weight… 9. `ACQ_WEIGHT_PLAYBACK_INDEX_INVALID_PATH_1`: Acquisition path 1 tried to integrate with an unknown weight… 10. `ACQ_SCOPE_DONE_PATH_0`: Scope acquisition for path 0 has finished. 11. `ACQ_SCOPE_OUT_OF_RANGE_PATH_0`: Scope acquisition data for path 0 was out-of-range. Please make sure that the input values are within the dynamic range of the ADC. See the module pages in the User Guide (QRM, QRM-RF) for the input ranges of the modules. 12. `ACQ_SCOPE_OVERWRITTEN_PATH_0`: Scope acquisition data for path 0 was overwritten. 13. `ACQ_SCOPE_DONE_PATH_1`: Scope acquisition for path 1 has finished. 14. `ACQ_SCOPE_OUT_OF_RANGE_PATH_1`: Scope acquisition data for path 1 was out-of-range. Please make sure that the input values are within the dynamic range of the ADC. See the module pages in the User Guide (QRM, QRM-RF) for the input ranges of the modules. 15. `ACQ_SCOPE_OVERWRITTEN_PATH_1`: Scope acquisition data for path 1 was overwritten. 16. `ACQ_BINNING_DONE`: Acquisition binning completed at least once. 17. `ACQ_BINNING_FIFO_ERROR`: Acquisition binning encountered internal FIFO error. The minimum time between the start of any 2 acquisitions for the QTM, QRM and QRM-RF modules is 300 ns. 18. `ACQ_BINNING_COMM_ERROR`: Acquisition binning encountered internal communication error. 19. `ACQ_BINNING_OUT_OF_RANGE`: Acquisition binning data out-of-range. Please make sure that your accumulated bin value is less than 2¹⁶ for binned acquisition and less than 2²⁰ for scope acquisition. 20. `ACQ_INDEX_INVALID`: Acquisition tried to process an invalid acquisition… 21. `ACQ_BIN_INDEX_INVALID`: Acquisition tried to process an invalid bin. Ensure `num_bins` is correct, as you can only access indices from `0` to `num_bins - 1`. 22. `TRIGGER_NETWORK_CONFLICT`: Trigger network has encountered a conflict. Ensure that triggers are at least 252 ns apart. See feedback for more details. 23. `TRIGGER_NETWORK_MISSED_INTERNAL_TRIGGER`: Trigger network missed an internal trigger. See feedback for more details. 24. `OUTPUT_OVERFLOW`: Output overflow. Ensure the combined output amplitude is within the DAC’s dynamic range. See User Guide for module ranges (QRM, QCM, QRM-RF, QCM-RF, QTM). 25. `CLOCK_INSTABILITY`: Clock source instability occurred. 26. `ACQ_INTEGRATOR_OUT_OF_RANGE_PATH_0`: Acquisition integration input data for path 0 was out-of-range. 27. `ACQ_INTEGRATOR_OUT_OF_RANGE_PATH_1`: Acquisition integration input data for path 1 was out-of-range.
`get_sequencer_status()` on a QTM module returns a FLAG	1. `DIO_COMMAND_OVERFLOW`: A sequencer command could not be accommodated by hardware. 2. `DIO_DELAY_OUT_OF_ORDER`: Commands were skipped due to being placed in wrong order or too close to one another. 3. `DIO_UNSUPPORTED_PULSE_WIDTH`: Unsupported pulse width was commanded. 4. `DIO_TIMETAG_DEADLINE_MISSED`: A timetag was received beyond the user-configured deadline time. 5. `DIO_TIME_DELTA_INVALID`: An `acquire timetags` window was closed and a source did not produce valid data within the window. 6. `DIO_COUNT_INVALID`: An `acquire timetags` window was closed and a counter overflow occurred (the accumulated value exceeded 2³²). 7. `DIO_THRESHOLD_INVALID`: An `acquire timetags` window was closed and the truth-table outcome for the window yielded the “invalid” outcome.