Skip to content

Troubleshooting & FAQ

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

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.)

Startup Checks

On the first run, FOAMFlask performs several checks to ensure your environment is correctly configured:

  1. Docker Installation: Checks if the Docker executable is in your system PATH.
  2. Permissions: Verifies that the current user can run Docker commands (without sudo).
  3. Image Availability: Checks if the required OpenFOAM Docker image exists.
    • If missing, it will automatically pull the image.
    • Note: This is a large download (several GBs). A warning will be displayed for metered connections.
  4. File Permissions: As mentioned above, it ensures container-generated files are owned by you.

IMPORTANT: Docker Configuration

The application uses specific bind mount paths to ensure compatibility with different user permissions (especially on Linux).

Caution

Do NOT modify the internal container mount paths in app.py or backend/startup.py. The application is configured to mount cases to /tmp/FOAM_Run inside the container. This /tmp path is critical because it ensures the directory is writable by ANY user (including your non-root host user). Changing this back to /home/foam or other strict directories will cause "Permission Denied" errors on Linux systems.

Note

Security Suppression: You may see # nosec B108 comments in the code near these paths. This is required to suppress Bandit security warnings because /tmp is a hardcoded path, which is flagged by default but is safe and intentional in this Docker container context.

Network Binding

By default, the application binds to 0.0.0.0 (all interfaces) to ensure it is accessible when running inside a container.

To change this behavior (e.g., for local development security), you can set the FLASK_HOST environment variable:

  • Container/Public Access (Default): FLASK_HOST=0.0.0.0
  • Localhost Only (Secure): FLASK_HOST=127.0.0.1

On startup, the application logs the listening address: FOAMFlask listening on: {host}:{port}

Note

Security Suppression: You may see # nosec B104 in app.py. This suppresses the Bandit warning for binding to all interfaces, which is intentional for the containerized deployment strategy.

Clone this wiki locally