Skip to content


How to solve the problem of installation stuck at 0%?

This type of problem is more common in cases where there are blockages in the company's environment where the tools are being used. Here are some of the behaviors observed:

  • Installation through the Wizard is stuck at 0%.
  • Failed to log in to BotCity Studio.
  • Authentication error when starting BotCity Runner.

The ideal solution in this case would be to ask the company's IT team for some access permissions. See more details about the URLs that require access in the section: Problems with blocking environments.

How to resolve dependency installation issues when running automation (ModuleNotFoundError)?

This problem usually occurs when the dependencies installation step is not done correctly. When running the code, a message is displayed regarding the installation of the packages: ModuleNotFoundError: No module named 'botcity’.

The first step is to ensure the same Python interpreter is used to install the dependencies and run the code. Something common is that the IDE creates a virtual environment for the project; if this virtual environment is used to install the dependencies but when running the system's "global" Python is being used, then this error will probably be thrown.

After ensuring the environment configuration is correct, use the same Python interpreter to install the dependencies: pip install --upgrade -r requirements.txt and run the code later.


If you are having a similar problem with another dependency when running your automation using BotCity Runner, check whether the dependency was correctly defined in the robot's requirements.txt file.

What are the features and limitations of a Community license on Maestro?

A new account that is created on Maestro has full access to the platform's functionalities (trial) for a period of 30 days. After this period of 30 days, access to the platform continues in the same way; the only difference is some limitations and access to some specific resources.

After the trial period, it is no longer possible to use the following features:

  • Credentials
  • Audit
  • Schedules
  • BotCity Documents

Additionally, the workspace will also have some limitations on other features:

  • Tasks - maximum of 10 tasks created per day
  • Automations - maximum of 1 automation process on the platform
  • Runners - maximum of 1 Desktop Runner on the platform

See more details about the difference between the plans and available resources by accessing this link.


The limitations of a Community license are focused on the orchestration step in Maestro.

The automation development stage does not have any limitations regarding the use of BotCity frameworks and plugins.

Where can I find content to learn more about using BotCity?

A great alternative to have a first contact with the tools is to access the courses available on BotCity Academy.

Additionally, you can also access the tutorials available on the documentation portal:

What to do when Runner seems stuck when executing a new task?

In sporadic situations, the Runner may seem stuck after pulling a new task for execution. In this situation, the execution is not started, and the Runner status remains as Executing task ... until the Runner is restarted.

Overall, what can cause this type of problem is the resources used by the previous execution, which have not been correctly finalized. Thus, when there is an attempt in the code to reaccess these resources, a conflict occurs because the operating system considers these resources already "in use".

A classic example is the use of web drivers in web automation. Without proper finishing, the web driver may continue to run even after the process is completed, causing this to affect the following executions.

A possible solution to this type of problem is to include treatments in the code to ensure that all resources allocated and used by the robot are finished correctly at the end of execution, even in cases where exceptions occur.

Following this good practice, every time the Runner performs this process, the environment will be "clean"; therefore, there will be no problems using specific resources.


You can also always consult the log.txt file generated by the Runner to verify any exceptions during the environment preparation and process execution.

How to find elements using computer vision in remote connections?

In some cases, for safety reasons, the customer does not allow the developer to access the runtime environment directly, forcing the construction of automation through a remote connection. In this way, some difficulties may arise when manipulating an application that is in a remote environment.

Through the BotCity Desktop Framework, we can control a remote machine via RDP using computer vision.

Listed below are some important points to be successful in searching for elements within this remote connection and computer vision scenario:

  • The RDP connection must be configured to use a constant resolution (it cannot be adaptive as a full screen, as it may vary from case to case).
  • The RDP connection must be configured to use a fixed experience parameter and not automatically based on connection speed.


You can configure the above parameters by clicking Show Options and then Display for resolution, and Experience for the connection quality parameter. When done, the screenshots will be constant between the connections.

Remember that it is essential to recapture visual elements after changing the remote access settings.

With a defined resolution configuration, you will be able to use BotCity Studio to take screenshots and manipulate elements of an application that is running in a remote environment.

What to do when getting the error OSError: screen grab failed when executing an automation using Runner in a remote environment?

The OSError: screen grab failed error is usually thrown when trying to perform an automation that uses computer vision to find elements in an environment where the remote connection has already been closed. This is because when closing the connection, the operating system will make the screen black, preventing bots from capturing the screen and making it impossible to search for graphic elements.

For this, BotCity offers two scripts to run bots that use the graphical interface of the environment without having to be connected to the session. These scripts disconnect the user's current session and redirect it to a terminal session, keeping the session and graphical interface active for BotCity Runner.

These scripts are available within the BotCity Studio SDK folder and can be used in the Runner execution settings. You can choose to execute them by starting the Runner using the startup parameter or before each task that the Runner will perform through the beforeTask parameter.



  • Startup: This script is available in the startup folder, and by setting it in the Runner configuration file, it will disconnect the current session and redirect it to a terminal session.

  • Console Session: This script is available in the scripts folder, and by setting it in the Runner configuration file, it will also have the function of disconnecting the current session and redirecting it to a terminal session, but also has the option to define the screen resolution for this new session.

See more details on the use and implementation of these scripts in the section Keeping your remote session active.

How to configure the encoding to avoid problems typing characters in RDP sessions on MacOS?

In some cases, when using Microsoft Remote Desktop on MacOS to start an RDP session, it is necessary to change the encoding setting to avoid problems typing special characters and also uppercase characters.

This problem can occur, for example, when trying to use the kb_type() function of the BotCity Desktop framework to type uppercase characters in a process running in a VM.

In this type of situation, the encoding set by default in Microsoft Remote Desktop for MacOS can cause the typing of characters not to work correctly within the VM.

To configure the encoding and avoid this type of problem in the RDP session, just access the Connections tab and check the Keyboard Mode > Unicode option in the Microsoft Remote Desktop application.

MacOS Remote Desktop