Troubleshooting Failed AI App Installations

This article covers troubleshooting a manual install over SSH that fails, since that's where you're responsible for the setup process yourself and most failures are things you can actually diagnose. For a manual install, the error messages involved are often vague or misleading, but most failures trace back to one of a small handful of causes. This article walks through the most common ones and how to tell them apart.

Not Enough RAM or Disk Space

This is the single most common cause of a failed AI app installation. If your server runs out of RAM while installing or starting an AI app, Linux's Out-Of-Memory (OOM) killer can terminate the process outright, and the error you see may look like a timeout or a generic crash rather than a clear "out of memory" message. As covered in our RAM and CPU usage article, this is especially common when installing a local model that's too large for your plan.

Disk space is a related but separate issue. AI models are large files, often several gigabytes each, and if your server runs out of disk space partway through downloading one, the download fails and can leave a corrupted or incomplete file behind. Checking your available disk space before you begin, particularly before pulling a new model through Ollama, is worth doing upfront rather than after a failed install.

Port Conflicts

Every app that runs a service, like a chat interface or an API, needs a specific network port to listen on. If another service on your server is already using that port, the new app can fail to start, even though the installation itself completed without error. This is more common on servers where multiple apps have been installed manually over time, since each one needs its own available port.

An Interrupted Installation

If you're doing a manual install over SSH and your connection drops partway through, whether from a network issue or an idle session timing out (covered in more detail in our timeouts and disconnections article), you can end up with a partial installation: some files in place, others missing, with no clear error telling you what actually happened.

Permission and Root Access Issues

Installing an AI app generally requires root access, which is exactly why AI apps are only available on Self-Managed VPS and VDS plans in the first place. If a manual install is attempted without the right privileges, or if file permissions get left in an inconsistent state from an earlier failed attempt, the installation can fail partway through, or appear to succeed while the resulting service fails to start.

It Might Be Running, Just Not Reachable

Not every "failed install" is actually a failed install. Sometimes the app or service starts up correctly on your server, but you can't reach it because a firewall is blocking the port it's running on, or because you're trying to access it at the wrong address. Before assuming an installation genuinely failed, it's worth checking whether the underlying service is actually running (most AI apps installed on Linux run as a managed background service, and their status can be checked directly) rather than only judging by whether a browser or client can connect to it.

Summary

Most failed manual AI app installations come down to a handful of causes: insufficient RAM or disk space, a port conflict with another running service, an interrupted SSH session, or a permissions issue. It's also worth confirming an app hasn't actually installed and started successfully but simply isn't reachable due to a firewall or connection issue, since that looks identical to a failed install from the outside. Checking service status and logs directly, rather than relying only on what a browser or client shows, is the most reliable way to tell these apart.