---
title: Troubleshoot
slug: /support/troubleshoot
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialExternalPreview from '@site/docs/_partial-external-preview.mdx';

<PartialExternalPreview />

This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.

## OpenSearch fails to start

Check that `OPENSEARCH_PASSWORD` set in [Environment variables](/reference/configuration) meets requirements.
The password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong.

## Langflow connection issues

Verify the `LANGFLOW_SUPERUSER` credentials set in [Environment variables](/reference/configuration) are correct.

## Memory errors

### Container out of memory errors

Increase Docker memory allocation or use [docker-compose-cpu.yml](https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml) to deploy OpenRAG.

### Podman on macOS memory issues

If you're using Podman on macOS, you may need to increase VM memory on your Podman machine.
This example increases the machine size to 8 GB of RAM, which should be sufficient to run OpenRAG.
   ```bash
   podman machine stop
   podman machine rm
   podman machine init --memory 8192   # 8 GB example
   podman machine start
   ```
   
## Port conflicts

Ensure ports 3000, 7860, 8000, 9200, 5601 are available.

## Langflow container already exists

If you are running other versions of Langflow containers on your machine, you may encounter an issue where Docker or Podman  thinks Langflow is already up.

Remove just the problem container, or clean up all containers and start fresh. 

To reset your local containers and pull new images, do the following:

1. Stop your containers and completely remove them.

    <Tabs groupId="Container software">
    <TabItem value="Podman" label="Podman">
    
        ```bash
        # Stop all running containers
        podman stop --all
        
        # Remove all containers (including stopped ones)
        podman rm --all --force
        
        # Remove all images
        podman rmi --all --force
        
        # Remove all volumes
        podman volume prune --force
        
        # Remove all networks (except default)
        podman network prune --force
        
        # Clean up any leftover data
        podman system prune --all --force --volumes
        ```
    
      </TabItem>
      <TabItem value="Docker" label="Docker" default>
    
        ```bash
        # Stop all running containers
        docker stop $(docker ps -q)
        
        # Remove all containers (including stopped ones)
        docker rm --force $(docker ps -aq)
        
        # Remove all images
        docker rmi --force $(docker images -q)
        
        # Remove all volumes
        docker volume prune --force
        
        # Remove all networks (except default)
        docker network prune --force
        
        # Clean up any leftover data
        docker system prune --all --force --volumes
        ```
    
       </TabItem>
    </Tabs>

2. Restart OpenRAG and upgrade to get the latest images for your containers.
   ```bash
   uv sync
   uv run openrag
   ```

3. In the OpenRAG TUI, click **Status**, and then click **Upgrade**.
When the **Close** button is active, the upgrade is complete.
Close the window and open the OpenRAG appplication.