# Troubleshooting

## Common pitfalls

| Symptom                                                                | Cause and fix                                                                                                                                  |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `ValueError: No existing parameters found for table ...`               | `update_parameters` needs existing parameters. Call `advise_parameters` or `set_parameters` first.                                             |
| My recommended parameters disappeared                                  | `set_parameters` replaces all the parameters. Use `update_parameters` to change only some of them. See {doc}`parameters`.                      |
| No avatars, only metrics                                               | `set_parameters` was called without `k` (or a DP epsilon).                                                                                     |
| `ValueError: Expected either k or fast_dp_epsilon to be set, not both` | After `advise_parameters`, pass `k=None` with the epsilon. See {doc}`processing`.                                                              |
| `imputation_return_data_imputed=True` has no effect                    | Pass `imputation_method` with it. See {doc}`parameters`.                                                                                       |
| `ValueError: No jobs found for display name ...`                       | No run has this exact name (case-sensitive). For a web job, run it in the web application first.                                               |
| I get the results of an older run                                      | Several runs have the same name: the most recent one is used. Give unique names, or use `create_runner_from_id`. See {doc}`advanced`.          |
| `UserWarning` when I call `run()` again                                | `run()` starts a new run. The warning gives the identifier of the previous run. Use `ignore_warnings=True` to hide it.                         |
| The server does not find the data of a replayed YAML                   | The file name in the YAML (`file: <table>.csv` or `.parquet`) must match the extension of the uploaded data. See {doc}`advanced`.              |
| `ImportError` on `ReportLanguage` or `JobKind`                         | Import `ReportLanguage`, `ReportType` and the other parameter enums from `avatar_yaml.models.parameters`, and `JobKind` from `avatars.models`. |
| The plot does not show in my notebook                                  | Use `runner.render_plot(..., open_in_browser=True)`.                                                                                           |

## Understanding errors

Most of your actions succeed. This section explains the errors that can
happen, and how to correct them.

1. `Timeout("The call timed out. Consider increasing the timeout with the 'timeout' parameter.")`

   The call takes too long on the server, usually during a job or the
   upload or download of a dataset. See [Handling timeouts](#handling-timeouts).

2. Validation errors

   Validation errors come from a bad input. The error messages use
   [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes):
   codes from 400 to 499 are user errors, codes from 500 to 599 are server
   errors.

   You can correct a user error by changing your parameters and trying
   again. The error message has this form:

   ```text
   Got error in HTTP request: POST https://company.octopize.app/reports.
   Error status 400 - privacy_metrics job status is not success
   ```

   It gives:

   - the HTTP method (`POST`, `GET`, ...);
   - the endpoint (`/reports`);
   - the status (`400`);
   - a message that explains the error (`privacy_metrics job status is not
success`).

   In this example, the report needs a successful privacy metrics job, but
   the privacy metrics job failed. Read the error of the privacy metrics job
   (see below), correct the input, and run again.

3. Failed jobs (`JobStatus.error`)

   `run()` does not wait for the jobs, so it does not raise when a job fails
   on the server. The result methods (`shuffled`, `privacy_metrics`, ...)
   raise `ValueError: Job <name> failed with exception: ...` when the job
   failed. To diagnose the failure, read the status and the `exception`
   property of the job:

   ```python
   from avatars.models import JobKind

   job = runner.get_job(JobKind.standard)
   print(job.status)  # JobStatus.error
   print(job.exception)  # explanation of the error
   ```

   Correct your input and run the job again.

4. Internal errors

   An internal error is an unexpected error on the server. It comes with a
   500 HTTP status code and the message `internal error`. Try again, if
   possible with different parameters.

   Our error monitoring notifies us of these errors at once. Contact your
   Octopize contact or <support@octopize.io> for help while we investigate.

## Handling timeouts

### Asynchronous calls

Many endpoints of the Avatar API are asynchronous: you ask for something
that runs in the background, and you get the result later with another
method, for example `runner.shuffled` or `runner.get_all_results` after
`runner.run`.

You do not need to wait for the job to finish. You can close your script,
come back later, reload the run and get the results:

```python
from avatars.models import JobKind

runner.run(jobs_to_run=[JobKind.standard, JobKind.privacy_metrics, JobKind.signal_metrics])
runner.statuses()  # the jobs are probably still queued or running
```

```python
# Take a coffee break, close the script, come back in 3 minutes
runner = manager.create_runner_from_name("my_run")  # in a new session
runner.statuses()  # {'standard': 'finished', ...}
avatars_df = runner.shuffled("my_table")
```