Skip to main content

Frequently Asked Questions

If you don't find an answer below or have a different question, please contact us on GitHub Discussions.

I cannot log in to the dashboard. I receive an error: ‘saleor ran into an unexpected problem’. What actions should I take?​

Make sure that you have set the environment variables.

There are two environment variables available for configuration:

  • API_URI (required): the URI of the GraphQL API endpoint of a running instance of Saleor. If you are running Saleor locally with the default settings, set API_URI to: http://localhost:8000/graphql/.

  • APP_MOUNT_URI: the URI at which the Dashboard app will be mounted. E.g., if you set APP_MOUNT_URI to /dashboard/, your app will be mounted at http://localhost:9000/dashboard/.

  • STATIC_URL: the URL where the static files are located. E.g., if you use S3 bucket, you should set it to the bucket's URL. By default, Saleor assumes you serve static files from the root of your site at http://localhost:9000/.

You can find the instructions on how to install and run the dashboard here:

https://github.com/saleor/saleor-dashboard#getting-started

I receive the 405 error. What does it mean?​

  • Please check if you have set the environment variables API_URI

  • Please check if the app is actually connected to the API

  • You can investigate the connection in the Network tab in your browser’s dev tools. Please look for GraphQL requests.

How can I run Saleor locally?​

We’ve recently introduced a new repository: saleor-platform. You can run all Saleor components (GraphQL API, Storefront, Dashboard) from one place by using Docker. Please, bear in mind that Saleor-Platform repository has only been designed for local development.

How can I add a custom payment gateway to Saleor?​

See Extending Saleor.

I cannot run Saleor server. I receive an error: ‘OSError: no library called "cairo" was found, no library called "libcairo-2" was found‘. What should I do?​

You must install the cairo and probably the pango library. For macOS, enter brew install pango cairo in your terminal. In the case of Linux and Windows systems, follow instructions from cairo and pango websites.

If you get this error, you are probably running Saleor outside the Docker Containers.
We recommend using the Saleor Platform, where this error shouldn't appear.

How to set up the environment variables?​

See Configuration.

Why is Razorpay not available in the storefront?​

Razorpay is currently only supported for implementation on the API. You need to separately prepare your storefront for using Razorpay.

How can I set taxes for my country?​

Saleor integrates with designated external tax service providers, specifically AvaTax and TaxJar. If you would like to use other tax providers, you will need to create a Saleor App.

For further details, please refer to the Saleor AvaTax App overview.

How can I create and integrate a custom tool to Saleor?​

Firstly, please figure out what the Saleor needs to know about the custom tool you would like to use. There is a possibility of direct communication between the storefront and the tool. This is the case with most content management systems.

If you need to connect Saleor with other tools, consider writing a plugin or creating an App extension.

How to check GraphQL responses and requests from the Saleor log?​

You can check GraphQL responses in the browser dev console, on the network tab.

Saleor also supports the OpenTracing protocol allowing full in-depth analysis of all GraphQL queries. You can read more about it here: Monitoring.

Why have images not been published after deploying Saleor to AWS?​

In this case, please check the file permissions. They are set as private by default. It's entirely up to the user which files they would like to publish.

You can find more information on the file permissions here: https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html

Can I run all Saleor components from one repository?​

You can run all Saleor components from one repository only by using saleor-platform. You will need to use Docker Compose for this. Please remember that the saleor-platform has only been designed for local development.

What is the current structure of Saleor?​

There are three separate apps (three repositories): the core - GraphQL API, Dashboard, and Storefront. You can find them in the links below. In order to run all three components, please follow the instructions from the readme section of each repository:

If you would like to run Saleor locally from one repository, you can use saleor-platform.

Does Saleor support mobile payment apps?​

Currently, Saleor does not support mobile payment apps such as Google Pay and Apple Pay. This feature is on our roadmap. However, we can’t yet tell when it will be available.

Where can I find the old version of Saleor with the Django views and templates?​

The old version of Saleor is available here.

Please bear in mind that we do not maintain it anymore.

Will the old version of Saleor (Django views and templates) receive updates?​

We do not maintain the old version of Saleor with Django views and templates. It will not receive any new updates. If you still would like to contribute to the project, we will be happy to review your request.

To install the latest stable versions of Saleor, storefront, and dashboard, please follow the instructions from the readme sections of the following repositories:

How can I contribute to the project?​

Saleor is an open-source e-commerce platform. We provide support and guidance for our community. You can contribute by creating pull requests on GitHub. We always welcome your ideas. If you have any questions or feedback, you can also reach us on Github Discussions.

Something went wrong with the payment, how can I check the gateway response?​

The easiest way is to use the API for fetching checkout payments with transactions and check such fields as error and gatewayResponse. There is a possibility to provide a checkout id in the payments filter, so firstly, you can fetch checkouts with ids and find the one you are looking for. Then you can use this id in the payment filter like this:

query {
  payments(
    last: 10
    filter: {
      checkouts: [
        "Q2hlY2tvdXQ6ZjlkZjAwMmItYWJmZC00OTZkLTljZDItZmU1NDBmZTRiNjIw"
      ]
    }
  ) {
    edges {
      node {
        id
        transactions {
          error
          gatewayResponse
        }
      }
    }
  }
}
Expand ▼

Please, note that you need MANAGE_ORDERS permission to perform this action.

How do I test Transactions without a real payment gateway?​

Please refer to the Payments guide on how to use the API.

You can also check the community resouces for dummy payment app that can mimic payment gateway responses.