Oh no! My Qiskit code isn’t working! What do I do??

Source: https://www.monkeyuser.com/2018/everytime/

So your Qiskit code is throwing errors and you don’t know why and maybe you want to throw your laptop out the window and possibly you’re regretting the life choices that have led you up to this point…

Don’t worry fellow Qiskitter — you are not alone!

Writing code of any kind is hard, and can be incredibly frustrating when things don’t work the way you expect. And you can multiply that feeling by ten when it comes to writing quantum software, as many users don’t have formal computer science backgrounds. On top of that, the industry is still fairly small, making it difficult to find help (or even just someone to rant to about your coding woes).

So with this blog post, we’re aiming to give you some guidance on how to resolve common issues when developing with Qiskit, as well as some general advice on debugging strategies and the coding mindset.

Option 1 — Is it a deprecation warning?

I’m putting this question right at the top because this is by FAR the most common issue that our users face. All of us at some point have tried running code that worked fine a few months ago but now has deprecation warnings pop up all over the place. It can be frustrating when this happens, but there are some simple ways to get around it:

First of all, it’s important to understand why you are seeing deprecation warnings. Software is a fast-paced and ever-changing industry, and quantum software is no different. Every professional software package has its own release cycle, with new versions being deployed frequently to fix bugs, deal with security vulnerabilities, and provide shiny new features to benefit users. For example, popular, established packages like Python and ECMA (JavaScript) put out a major release every year, as well as several other minor releases. In contrast, the Qiskit packages are still in their early development stages. Most are between 6 months to 5 years old and have not yet reached a major version release milestone yet (by which we mean versions 1.0.0 or later). This means you can expect shorter release cycles and a higher degree of fluctuation in functionality, resulting in more frequent deprecation warnings. This is to be expected for an emerging technology like quantum computing, where things are still experimental and new research is published frequently.

So what does this mean for fixing your deprecation warnings?

Well, there are a couple of options:

Deprecation warnings — Solution 1: Keep your Qiskit code up-to-date!

This option may be the most hassle, but those deprecation warnings are there for a reason! If you want to make sure you are using the best, most up-to-date Qiskit code, then make sure you are regularly checking your work and following the guidance in the deprecation warnings when you come across them, particularly if it’s code that you use frequently. This ensures the work you’re doing stays on the sharpest edge of this cutting edge quantum technology 😉

Deprecation warnings — Solution 2: Pin your Qiskit version

We know, we know, you don’t have time to keep your code updated with the latest Qiskit version all the time. The release cycles are frequent, you’re a busy person, and you have better things to do in the evening before a Big Demo™ than refactor all your code to get rid of those pesky deprecation warnings.

In this case the best short term solution is to pin your Qiskit version. This means specifying in your Python environment exactly which version of Qiskit you want to be installed.

So instead of doing pip install qiskit-terra (which will install the latest stable version by default), you can do pip install qiskit-terra==0.x, which will install the specific version you want to use.

For example, if qiskit-terra v0.29.0 or later causes deprecation warnings for your code but v0.0.28 doesn’t, you can do pip install qiskit-terra==0.28.0

Alternatively, if you want to keep using a specific version but want to keep up with the latest patch releases for that version you can use ~= instead of ==.

So, if qiskit-terra v0.29.0 or later causes deprecation warnings for your code but v0.28.0 doesn’t, AND you want to install any of the patch releases that came out between v.0.28.0 and v.0.29.0 you can do pip install qiskit-terra~=0.28.0 .

Option 2 — Was the error caused by a something in your code?

If deprecation warnings aren’t the cause of your errors, there may be some issues with how you’ve written your code that’s causing a problem. In this case, you’ll need to do some debugging to figure out what went wrong.

Debugging is an incredibly useful skill for software development, but one that takes time to grow. The only way to get better at it is to keep dealing with lots of errors again and again (sorry folks, that’s just how it is). Every developer has a different preferred process for debugging, and you’ll need to gradually find the way that suits you best. But here are some general tips that may help you:

Look at the stack trace — does it offer any helpful clues?

The ‘stack trace’ is the long error message that pops up when something goes wrong. It can feel completely incomprehensible the first (or first hundred) times you see one. They usually look something like this:

A long message like this can be overwhelming at first but the main thing to know is that the very last line of the error message tells you what (at the highest level) is causing your code to fail. These final messages normally all have the same structure: “ErrorType: some explanation of the error”. This is the first thing to decipher when your code breaks.

Advanced (most useful for Qiskit contributors): If you scroll back to the top and look more deeply at the stack trace, you can see that it shows you the path the code is taking during runtime. It will usually print the name of the file followed by the specific line and the function being called, followed by the next and the next until it hits the function that is causing the error. Understanding the path your code is taking is useful for debugging those trickier errors so you can verify the correct methods/classes are being called.

Understand the different error types

The error message at the end of the stack trace usually starts by indicating what type of error is being thrown. If you’re familiar with the different types, then this can help you more quickly understand what is going wrong and how to fix it. For more detail on the most common types of errors that could be raised, you can check the Python documentation here.

Don’t forget to Google it!

Many of the errors users typically face won’t necessarily be Qiskit or quantum computing specific — they may be common Python errors. These are much easier to Google and find solutions for on StackOverflow or similar sites.

Source: Reddit r/ProgrammerHumor

Some of the most common Python errors you may come across when developing with Qiskit are:

• ModuleNotFoundError: cannot find module xyz means you probably don’t have xyz installed or you’re importing it from the wrong place
• NameError: xyz is not defined means you’re probably trying to do something with xyz before you’ve declared it (maybe you mis-typed xyz when you actually meant wxyz, or in a jupyter notebook maybe you need to go back and re-run some earlier cells)
• Syntax Error means there’s a typo somewhere or an incorrect indentation

If you think the error is too Qiskit-specific and you can’t find a pythonic solution, you can still Google it, with sites like Quantum Computing Stack Exchange being useful forums to look for solutions.

Option 3 — Was the error caused by a bug in Qiskit?

No codebase is perfect and even large projects like Qiskit may experience bugs from time to time. If you think you’ve found a bug in the Qiskit codebase, then there are a few things you can do.

First of all, be 1000% sure that the bug is caused by Qiskit itself and not your own code. Before jumping to conclusions, make sure you’ve checked your own code thoroughly and referred to the documentation. Is the error you’re seeing actually intended functionality? Are you implementing the class/function correctly with the appropriate arguments? Always double check that you understand what a specific class or function is built to do, not just what you want it to do.

If you’ve done all that and are still sure the issue is with Qiskit, then the best course of action is to identify as best you can where the bug is and then head to GitHub to report it. Go to the specific repo for the Qiskit package that has the bug and open a ‘Bug Report’ issue. Most of the repos have this specific issue template.

Follow these top tips for opening good bug report issues:

• Check if an open issue already exists for the bug you are reporting before opening a new one (you can filter by the “bug” label in the issue search tab). If someone has already reported it, leave a comment or a thumbs up to let maintainers know that it is a common issue that multiple users are facing.
• Add the Qiskit version you found the bug in to the description.
• Paste the stack trace for the error in the description.
• Add a Minimum Reproducible Example to the description. i.e. the minimum amount of code needed for someone else to also see the error when they run it.
• Tell us in the issue description what you would have expected (i.e. no error, a different error message, clearer documentation etc.)

Following the above tips makes it as easy as possible for a maintainer to understand the issue and reduces the time it takes to get it fixed.

Option 4 — Need a break?

Sometimes when you’ve been working non-stop on a problem, it can feel like it’s impossible to solve and no matter what you do nothing works and life sucks. When I get to this point, I realize that it’s probably time for a break. Time to get out of the house, stop staring at my screen for a bit, maybe get a snack and/or cuddle a cute pet. This isn’t giving up, it’s just taking a pause to recharge and then coming back to the problem with fresh eyes, which could make all the difference. When you’re so focused on one problem, your brain gets tired and it can be hard to see the forest from the trees, so never underestimate the importance of taking regular breaks.

Option 5 — Still don’t know what’s wrong?

If you’ve followed all of the above steps and still aren’t sure what to do with your issue, the best option is to reach out to other members of the Qiskit Community. Chances are that someone else may have encountered the same issue before or could help point you in the right direction for a solution.

To find out the best way to get support for an issue, check out https://qisk.it/support

And there you have it! 5 steps to follow whenever you get stuck writing Qiskit code. Bookmark this blog for future use when you’re in danger of throwing your laptop out of the window in debugging frustration 😉

Happy coding, fellow Qiskitters!