# Troubleshooting

### Why does quilc change the qubits used in my program?

By default, `quilc` may change the qubits used in your program to fit the topological constraints of the quantum processor the program is being compiled for.  This process is called "rewiring" and the default strategy tries to maximize for fidelity. If this is undesirable, a different rewiring strategy can be configured by including a special `PRAGMA` instruction in your program. See [QPU vs. Simulator (QVM)](/qcs/guides/qpus-vs-qvms.md#rewiring) for more details.

### I get an "Accessor not found" error when I try to run a job

This means that the [QCS QPU Gateway](/qcs/guides/access-a-qpu/qcs-qpu-gateway.md)is unavailable for the target QPU. This is usually due to a service interruption, but if you are in an environment that has direct access to a QPU endpoint (like JupyterHub), you can use the "Direct Access" connection strategy to effectively bypass the Gateway and avoid the error. How you do this depends on your client library: 

* pyQuil: [QCS Gateway and execution options](https://pyquil-docs.rigetti.com/en/stable/introducing_v4.html#qcs-gateway-and-execution-options).
* qcs-sdk-rust: [ExecutionOptions](https://docs.rs/qcs/latest/qcs/qpu/api/struct.ExecutionOptions.html)

### I get an error that says "This API route has been retired."

We do not permit any breaking changes to the arguments, return values, or behavior of QCS API routes. However, routes are occasionally superseded in order to facilitate evolving the system. When this occurs, we maintain the existing route for some amount of time, but consider it deprecated. Once we are confident that nearly all users have migrated to the new route and that there is an easy upgrade path for those who haven't, we modify the route to return a static error response indicating that the route has been retired.<br>

Because the vast majority of QCS users rely on the libraries we provide rather than writing requests against the OpenAPI schema directly, the typical upgrade path is simply to upgrade the versions of the QCS libraries.

### I tried to access the readout data for my job and got a `RegisterMatrixConversionError`

This means that your program generated non-rectangular readout data. This is usually due to your program using features like mid-circuit measurement or dynamic control flow. See [QPU vs. Simulator (QVM)](/qcs/guides/qpus-vs-qvms.md#qpu-readout-data) for more details on why and how to navigate[QPU vs. Simulator (QVM)](/qcs/guides/qpus-vs-qvms.md#raw-qpu-readout-data) so you can build a structure tailored to your program's intent. See your client library documentation for how to access raw readout data:

* pyQuil: [Accessing raw execution data](https://pyquil-docs.rigetti.com/en/stable/introducing_v4.html#qcs-gateway-and-execution-options)

### I get an error that says "No refresh token is configured within selected QCS credential"

Credentials are needed to authenticate all requests to the QCS API and this error indicates that they are missing or have been configured incorrectly. Follow the instructions in [QCS Credentials](/qcs/guides/qcs-credentials.md) for your environment of choice to get a valid set of credentials.

### My program is timing out or my script hangs until I cancel it

This could be a problem with the size of your program, `quilc`, [`qvm`](#user-content-fn-1)[^1], or an issue connecting to the QCS API. Before proceeding, be sure to get a diagnostics report per the instructions in [Gathering Diagnostics](/qcs/troubleshooting/gathering-diagnostics.md). We can use this report to identify where connection problems are happening, if at all.

#### A connection cannot be made to `quilc` or `QVM`

If the report says that `quilc` (and/or QVM, if using) is not available, then make sure it is running in server mode per the instructions in [Install Locally](/qcs/getting-started/set-up-your-environment/installing-locally.md#start-the-compiler-and-qvm).&#x20;

#### A connection cannot be made to the QCS API

If a connection can't be made to the QCS API, first check the [Rigetti status page](https://rigetti.statuspage.io/) to make sure there are no ongoing incidents. If there are, please wait until we can resolve the issue. Otherwise, make sure your credentials are up-to-date by either [Using the QCS CLI](/qcs/guides/using-the-qcs-cli.md), by logging in to QCS and [following these instructions](https://qcs.rigetti.com/auth/token) to refresh your credentials, or by stopping and starting your JupyterLab server per the instructions in [JupyterLab IDE](/qcs/getting-started/set-up-your-environment/jupyterlab-ide.md#stop-or-change-your-server).

If none of these solutions work, please [Report an Issue](/qcs/troubleshooting/report-an-issue.md) and include a copy of the diagnostics report you gathered.

#### A successful connection can be made to all required services but my program still times out

If a successful connection can be made to each service you are using, then the problem may come down to the size of your program and the timeouts used to compile and/or execute them. Try compiling a trivial program that uses only one qubit. If a small program works, then try your original program with a longer compiler and execution timeout. How this is configured depends on your client library:

* pyQuil: [get\_qc parameters](https://pyquil-docs.rigetti.com/en/stable/apidocs/pyquil.api.html#pyquil.api.get_qc)
* qcs-sdk-rust: [Compiler options](https://docs.rs/qcs/latest/qcs/compiler/quilc/struct.CompilerOpts.html), [QVM options](https://docs.rs/qcs/latest/qcs/qvm/struct.QvmOptions.html), and [execution options](https://docs.rs/qcs/latest/qcs/qpu/api/struct.ExecutionOptions.html#method.timeout)

### I got an error that mentioned the Engagements API was deprecated

If you submit a job and get an error message that links you here and/or says:

> The engagements API is deprecated and does not support the requested QPU. This likely means you are using an out-of-date client and should upgrade to the latest major version.

Then you are likely using an old version of a client library that is not supported for execution against the requested Rigetti QPU. You should upgrade your client library to the most recent version to get the latest features and to be able to execute against current QPUs. As a general rule, it's a good idea to keep your client library up-to-date as much as possible to get the latest features and fixes. Here are some potential upgrade paths:

* pyQuil v3: Upgrade to the latest available version. Read through [Introducing pyQuil v4](https://pyquil-docs.rigetti.com/en/stable/introducing_v4.html) for a guide to the major changes made in v4 and the [4.0.0 entry in the changelog](https://pyquil-docs.rigetti.com/en/stable/changes.html#section-7) for a comprehensive list of every breaking change.
* `qcs-api-client-python`: Remove any calls to the Engagements API and consider migrating to [qcs-sdk-python](https://github.com/rigetti/qcs-sdk-rust/tree/main/crates/python) or [pyQuil](https://github.com/rigetti/pyquil) for executing jobs.

[^1]: Minor point on this - I tend to write `qvm` as the package or QVM as its name, but not the mixed `QVM`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rigetti.com/qcs/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.