Repository navigation
Troubleshooting
If you use Docker Desktop: check that Settings → Advanced → Allow the default Docker socket to be used is enabled. The app connects over the default Unix socket, and Docker Desktop can be configured not to create it.
If you use Colima, OrbStack, Rancher Desktop, or podman: the app cannot currently reach these. It looks for Docker Desktop's socket only, and a GUI app does not inherit the DOCKER_HOST you set in your shell. There is no workaround from the UI yet — this is a known gap and a tracked issue.
If Docker Desktop is starting up: the check reports unreachable rather than hanging, so wait for the whale icon to settle and click Re-check.
Known issue. macOS gives Finder-launched apps a minimal PATH that excludes /usr/local/bin and /opt/homebrew/bin, which is where Docker and npm install their CLIs. The button cannot find them.
Run the command yourself and click Re-check:
docker pull microfluidica/openfoam:13
Launching the app from a terminal instead of Finder also works, since it then inherits your shell's PATH:
open -a "OpenFOAM Studio"
The app runs a local server on port 3456. This screen means it could not.
Almost always something else is already on that port — usually an orphaned backend from a previous run. Current builds detect and reuse an existing backend instead of failing, so if you see this on an older build, updating fixes it. To clear it manually:
lsof -ti:3456 | xargs kill -9
On Windows:
netstat -ano | findstr :3456
then taskkill /PID <PID> /F.
The Geometry and Results tabs need hardware-accelerated WebGL. If a viewer is black while the rest of the app is fine, your GPU driver is likely the problem.
The app detects a lost WebGL context and offers a Retry rather than blanking. If it recurs, launch with software rendering — slower, but it draws:
OFS_DISABLE_GPU=1 open -a "OpenFOAM Studio"
It is not. microfluidica/openfoam:13 is several GB and progress streams into the setup log line by line. Give it time on a normal connection.
Most often a small model losing patch-name consistency between blockMeshDict and the 0/ field files. Options, in order of effectiveness:
- Switch to a stronger model — see Configuring an AI provider. This is the single biggest lever.
- Tell the agent what broke. Paste the
blockMesherror into the chat; diagnosing its own output is what it is built for. - Fix it by hand in the editor. The files are yours.
A physics problem, not an app problem — but the agent is useful here. Ask it directly: "the pressure residual stalled at 1e-4, what should I change?" It reads the run log and the case files together.
Common causes: a time step too large for the mesh (Courant number), a poor initial field, or an inappropriate turbulence model for the regime.
By design. The recovery loop stops after three cycles rather than burning tokens on a case it cannot repair. The chat holds every diagnosis it tried — usually enough to see what it was circling around. Adjust the case by hand and run again.
Settings shows only whether a key is present, never its value. Check that the provider selector matches the key you pasted — an Anthropic key with OpenAI selected fails as though it were missing.
The app also reads ANTHROPIC_API_KEY, OPENAI_API_KEY, and GOOGLE_GENERATIVE_AI_API_KEY from the environment, but a GUI app does not see variables set in your shell profile. Prefer Settings.
Results need foamToVTK output, which the run pipeline produces automatically. For a case solved outside the app, or one solved before this feature existed, the Results tab offers a one-click conversion of the existing time steps — no re-solve.
Gatekeeper on an unsigned binary, not a real corruption. See Installation — right-click → Open, or clear the quarantine flag.
Open an issue: github.com/PKrunal26/openfoam-studio/issues
Worth including: your OS and version, which provider and model, what you asked for, and the relevant part of the Logs tab. The Commands panel showing which command exited non-zero is usually the fastest clue.
MIT licensed. Not approved or endorsed by OpenCFD Limited, owner of the OPENFOAM and OpenCFD trademarks.