Skip to content

Troubleshooting & FAQ

Jump to bottom
Dhruv Haldar edited this page Jun 5, 2026 · 3 revisions

Troubleshooting & FAQ

This is a living document designed to help users resolve common issues encountered while setting up and running FOAMFlask.

Common Issues

Path Issues: Cannot Find OpenFOAM Root or Case Directory

Issue Description: The UI throws an error or fails to load when trying to set the OpenFOAM root or case directory. Resolution:

  1. Use Absolute Paths: Ensure you are entering the full, absolute path to your directories (e.g., /home/user/OpenFOAM/ instead of ~/OpenFOAM/).
  2. Check Permissions: Verify that the user running the FOAMFlask backend has read/write access to the selected case directory.
  3. Reset Configuration: If the app is stuck in a loop, delete the case_config.json file in the root directory to reset your saved paths to default.

Missing Dependencies: Python or Plotly Errors

Issue Description: Terminal shows ModuleNotFoundError or the web UI fails to render plots. Resolution:

  1. Virtual Environment: Ensure your Python virtual environment is actively running before starting app.py.
  2. Reinstall Requirements: Run pip install -r requirements.txt again to ensure all packages (including Flask and custom parsers) are up to date.
  3. Browser Cache: If plots aren't rendering, perform a hard refresh (Ctrl+F5) in your browser or clear the cache to ensure the latest frontend JS/Plotly libraries are loaded.

Plotting Errors: Missing Fields

Issue Description: Realtime plots do not show specific turbulence or aerodynamic fields (like nuTilda, omega, or k). Resolution: FOAMFlask's plotting engine automatically detects available fields. If a field is missing from the plot, it means the OpenFOAM solver hasn't written that data to the time directory. The plotter will gracefully ignore missing fields without crashing. To fix this, ensure your OpenFOAM controlDict and solver setup are properly configured to output those specific variables.

Docker Configuration & Permissions

Docker Desktop Warning (Windows)

Issue Description: Warning on the backend console: WARNING:FOAMFlask:[FOAMFlask] get_tutorials called but Docker Desktop is not running. Frontend shows an empty drop-down for Load Tutorial. Explanation: The application is trying to access Docker Desktop, but it is either not running or not installed. Resolution:

  1. Install Docker Desktop (if not already installed) from Docker's official website. (Note: This build was tested on 4.45.0 (203075)).
  2. Start Docker Desktop and wait for it to fully initialize (look for the Docker Desktop running icon in your system tray).
  3. Restart the FOAMFlask application.
  4. Tip: In Docker Desktop settings, enable Start Docker Desktop when you sign in to your computer for automatic startup.

Docker Socket Permissions (Linux)

Issue Description: "Permission denied" error when trying to access the Docker socket (e.g., cannot connect to Docker daemon). Explanation: Your Linux user does not have permission to access the Unix socket /var/run/docker.sock. Resolution:

  1. Add your user to the docker group: 
    sudo usermod -aG docker $USER
  2. Apply the group changes:
  • Method A (Temporary): Run newgrp docker in your current terminal.
  • Method B (Permanent): Log out and log back in (recommended).
  • Method C: Restart your computer. Verify access by running: 
    docker run --rm hello-world

File Permissions (Linux)

Issue Description: Files created by the OpenFOAM container (e.g., tutorial files, logs) are owned by root and cannot be deleted by the host user.

Explanation: By default, Docker containers run as root, so files written to host system bind mounts are owned by root.

Resolution: FOAMFlask includes an automated startup check to handle this: On the first run, it performs a "dry run" by launching a container to write a test file. It attempts to delete this test file. If deletion fails (Permission Denied), it automatically configures future containers to run with your current host user ID (UID) and group ID (GID). This ensures all subsequent files created by OpenFOAM are owned by you. (Note: You will see a "System Check" modal on startup while this verification takes place.)

Clone this wiki locally