> ## Documentation Index
> Fetch the complete documentation index at: https://docs.briefer.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> How to solve the most common issues with Briefer deployments.

This page covers the most common issues with Briefer deployments and how to solve them.

Please make sure to update Briefer to the latest version before starting to troubleshoot. We're constantly improving the project and fixing bugs, so it's possible that your issue has already been solved in newer versions.

<CodeGroup>
  ```bash Pip upgrade theme={null}
  # If you're using pip, upgrade with:
  pip install --upgrade briefer
  ```

  ```bash Docker upgrade theme={null}
  # If you're using Docker, upgrade with:

  # 1. Remove the old container (find it with docker ps -a)
  docker rm <your_container_id>

  # 2. Pull the latest image (docker pull --no-cache briefercloud/briefer:latest)
  docker pull --no-cache briefercloud/briefer:latest

  # 3. Run it again (you might also want to delete old volumes)
  docker run -d \
    -p 3000:3000 \
    -v briefer_psql_data:/var/lib/postgresql/data \
    -v briefer_jupyter_data:/home/jupyteruser \
    -v briefer_briefer_data:/home/briefer \
    briefercloud/briefer
  ```
</CodeGroup>

<Info>
  In case you need assistance, please don't feel shy to open an issue or send us
  an email at [contact@briefer.cloud](mailto:contact@briefer.cloud). We're here
  to help.
</Info>

## Solving common issues

<Accordion title="I can access the web application, but the sign-in is not working">
  If you're running Briefer in another machine, for example an external server, Raspbery Pi, etc - make sure you have enabled HTTPS for your current setup while accessing Briefer on port `3000`.

  In case you can't enable HTTPS or just want to try it out over HTTP, you can run Briefer over HTTP by setting the `ALLOW_HTTP` environment variable to `true`:

  ```bash theme={null}
  ALLOW_HTTP=true briefer
  ```

  Note that using `ALLOW_HTTP` will *not* set the session cookie as Secure, thus allowing you to sign in using HTTP. We don't recommend using this option production.

  Furthermore, if you're using an older version of Briefer, you might need to delete older volumes which might contain conflicting data. You can do that by running:

  ```sh theme={null}
  # If you have data on disk (like files), you may want to back those files up before running these commands
  # Still, these commands do *not* delete the data in your database (notebooks, dashboards, users, etc)
  docker volume rm briefer_jupyter_data
  docker volume rm briefer_briefer_data
  ```
</Accordion>

<Accordion title="I can't access the web application">
  If you're not able to access the web application, Briefer is either not running or not exposed to the internet (or within your local network). The latter is the most common issue.

  To check if Briefer is running, SSH into your server and run `docker ps`. You should see a container using the image `briefercloud/briefer` or `briefercloud/briefer-web`. If you don't see it, Briefer is not running.

  If Briefer is running, have a look at its logs and see if there are any errors. You can do that by running `docker logs <container_id>`, where `<container_id>` is the ID of the Briefer container.

  Finally, make sure that you've exposed your server to the internet or your local network. You can do that by allowing traffic on port `3000` and creating the necessary DNS records to access the host. Finally, please ensure that the container's port is bound to the host's port (`3000`).
</Accordion>

<Accordion title="I can access the web application, but I can't run code">
  This problem is likely due to an issue with the WebSocket connection that Briefer uses to send code execution requests to the backend (and document edits).

  If you're using a reverse proxy, make sure that it's configured to allow WebSocket connections. You can do that by adding the following configuration to your Nginx reverse proxy:

  ```nginx theme={null}
  # WebSocket settings
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "Upgrade";

  # Disable buffering for WebSocket
  proxy_buffering off;
  proxy_cache_bypass $http_upgrade;

  # Timeouts for long-polling
  proxy_read_timeout 60s;
  proxy_send_timeout 60s;
  ```

  If you're using a different reverse proxy, make sure to check its documentation for WebSocket configuration.
</Accordion>

<Accordion title="I can access the web application, but it can't talk to the API">
  In this case, it's likely that the web process is running, but the API is not.

  If the API is running, have a look at its logs and see if there are any errors. You can do that by running `docker logs <container_id>`, where `<container_id>` is the ID of the API container or the monolithic Briefer container in case that's what you're using.

  Check if it complains about any missing environment variables or if there's any other straightforward error that you can solve.

  If you can't figure out what's happening, please [open an issue here](https://github.com/briefercloud/briefer/issues).
</Accordion>

<Accordion title="I get a 500 error whenever I try to access Briefer">
  This is likely an issue with encrypting and decrypting tokens. It usually happens when you have lingering data from a previous execution while having changed Briefer's encryption keys.

  To fix this issue, start by clearing your browser's cookies and local storage. Then, try accessing Briefer again.

  <Tip>
    You can clear cookies and local storage exclusively for Briefer's address by
    using the *Application* tab in Chrome's DevTools.
  </Tip>

  If you still can't access Briefer you may have to remove Briefer's old docker volumes.

  ```sh theme={null}
  docker volume rm briefer_jupyter_data
  docker volume rm briefer_briefer_data
  ```
</Accordion>

<Accordion title="I'm having issues with my Postgres SSL settings">
  Briefer accepts the following environment variables to configure the SSL connection to your Postgres instance:

  * `POSTGRES_SSL_DISABLED`: Set this to `true` to disable SSL.
  * `POSTGRES_SSL_REJECT_UNAUTHORIZED` (optional): Set this to `true` to reject unauthorized (self-signed) SSL certificates.
  * `POSTGRES_SSL_CA`: (optional): The path to the CA certificate file to validate the server certificate.

  <Note>
    If you're deploying Briefer using our Helm chart, you can set these values in the `values.yaml` file as `api.env.postgresSslDisabled`, `api.env.postgresSslRejectUnauthorized`, and `api.env.postgresSslCa`, respectively.
  </Note>

  If you're having issues with your Postgres SSL settings, make sure that you've set these environment variables correctly.

  By default, Briefer's connection will have the same SSL settings as using `sslmode=prefer` in a Postgres connection string.
</Accordion>