Local.ai help
Windows Local.ai installation troubleshooting
Use these checks when the Docker-on-Windows setup does not start or open as expected. Each issue stays within the CPU container path currently documented by Officeers:
docker run -p 8080:8080 --name local-ai -ti localai/localai:latestThis page covers the container engine, port 8080, the named local-ai container, the local service, and model-download checks. It does not document other setup paths.
Issue 1
Docker is not recognized
- Symptom
- PowerShell cannot use the
dockercommand. - Cause to verify
- Docker may not be installed yet, Docker Desktop may not be started, or the current PowerShell session may predate the installation.
- Safe next step
- Finish the official Docker installation, start Docker Desktop, open a fresh PowerShell session, and confirm the engine responds with
docker psbefore rerunning the unchanged LocalAI command.
docker psIssue 2
The Docker engine is not running
- Symptom
- The LocalAI command cannot reach Docker.
- Cause to verify
- The Docker container engine is stopped or unavailable to the CLI.
- Safe next step
- Start Docker Desktop, run
docker psto confirm the engine responds, and then retry the documented LocalAI command.
docker psIssue 3
Port 8080 is already in use
- Symptom
- The documented command cannot publish the service on port 8080.
- Cause to verify
- Another Windows process is listening on port 8080.
- Safe next step
- Inspect Windows listeners with
netstat -ano, identify the process that owns the reported PID, and free port 8080. Then rerun the unchanged command so the expected URL remainshttp://localhost:8080.
netstat -anoIssue 4
The local-ai container name is taken or the container exited
- Symptom
- The named container cannot be started by the documented command.
- Cause to verify
- A container named
local-aialready exists, or that container stopped after starting. - Safe next step
- Inspect all containers and read the existing container's startup output. If it is the intended container, start it with
docker start local-ai. Removing and recreating a container is an intentional, data-affecting choice; do that only when you mean to discard that container.
docker ps -a
docker logs local-ai
docker start local-aiRead the Docker container list referenceRead the Docker logs reference
Issue 5
The service does not open at http://localhost:8080
- Symptom
- The local service is not reachable at the expected URL.
- Cause to verify
- The container may not be running, its startup output may show an error, or port 8080 may not be published by the container command.
- Safe next step
- Check
docker ps, readdocker logs local-ai, and confirm that the published port is 8080. Keep the diagnosis on this documented container-and-port path.
docker ps
docker logs local-aiIssue 6
The model download fails
- Symptom
- LocalAI cannot complete the selected model download.
- Cause to verify
- The documented checks are network connectivity, available disk space, the container logs, and whether the selected model source requires authentication. An HTTP
401or403response means authentication is required by that source. - Safe next step
- Check the network connection and available disk space, then inspect
docker logs local-aifor the download result. If the logs show 401 or 403, address authentication for the selected model source.
docker logs local-ai