Fixing a Docker Container That Won't Start

Stay Calm - Work In Order

The single biggest mistake with a stuck app is thrashing - deleting things, re-pulling wildly, changing five settings at once. When you do that, you can turn a small problem into a real one. So we slow down.

A container is just a small, self-contained copy of an app. It has its settings stored safely in a folder called appdata. When the container won't start, the app's files are almost always still fine - we just need to find what is stopping it from launching.

• Look - read the log, note the exact message.
• Guess once - match the message to a common cause.
• Change one thing - fix that, then try to start it.
• Repeat - if it still fails, undo your change and try the next cause.

Read the Container's Log First

Before you change anything, read the log. The log is the app talking to you - it usually says, in fairly plain words, why it would not start. This one habit solves most cases.

You are hunting for words like "port is already allocated," "permission denied," "no such file or directory," or "exited." You do not need to understand every line. Find the one angry line near the bottom and note it down word for word.

• Go to the Docker tab in Unraid's web page.
• Find the app in the list of containers.
• Click its icon and look for "Logs" in the little menu.
• Read the last several lines - the newest messages are at the bottom.

The Common Causes, At A Glance

Almost every won't-start problem falls into one of a handful of buckets. Here they are, roughly in the order they tend to happen. The next pages take each one slowly.

Match the angry line from your log to the closest row here, then jump to that chapter. If nothing matches, work through them in order - it does not take long.

A Port Is Already In Use

A "port" is like a numbered door the app listens on. If two apps try to use the same door number, the second one cannot start. This is one of the most common causes, and an easy fix.

You will usually see a log line like "port is already allocated" or "address already in use." It means another container - or Unraid itself - is already using that number.

• Open the app's settings by clicking its icon and choosing Edit.
• Find the "Port" field - it shows a number the app uses.
• Change the first (host) number to a nearby free one, like 8081 instead of 8080.
• Leave the container's own inside number as it was, then apply.

A Wrong Or Duplicated Folder Path

Apps are told where to find their files using "path mappings" - a link between a folder inside the container and a real folder on your server. If that link points to the wrong place, or is listed twice, the app trips over it.

In the log this often looks like "no such file or directory" or the app starting but showing an empty library. It means the app is looking somewhere that does not exist, or somewhere with nothing in it.

• Open the app's Edit page and look at each path mapping.
• Make sure the server-side folder actually exists and is spelled right.
• Watch for two mappings pointing at the same inside folder - remove the duplicate.
• Check for a stray space or a wrong slash in the folder name.

Permission Problems On appdata

Sometimes an app cannot start because it is not allowed to read or write its own settings folder. This shows up as "permission denied" in the log. It is common after moving files around or restoring from a backup.

Think of it like a locked drawer: the app has the right drawer, but not the key. We just need to hand back the key by fixing the folder's ownership and permissions.

• Unraid includes a tool often called the "New Permissions" tool - look for it under Tools or Settings.
• Some folks use the "Fix Common Problems" plugin, which can spot permission issues.
• Run the permissions fix on the appdata share, then try starting the app again.

A Bad Update Or Broken Image

The "image" is the app's program code that Unraid downloads. Now and then an update lands badly, or a download finishes half-broken, and the app that ran yesterday will not start today.

The tell-tale sign is timing: it worked fine, you (or an automatic update) updated it, and now it fails. The log may mention the app crashing right at startup.

• First, force a fresh update to re-download the image (covered on a later page).
• If a specific version broke it, some apps let you choose an older, stable version tag.
• Reinstall from "Previous Apps," which keeps your settings, to get a clean copy.
• Check the app maker's page - others often report a bad release quickly.

Not Enough Memory Or Space

An app can fail to start simply because the server has run low on memory (RAM) or on disk space. When the tank is empty, apps stall, crash, or refuse to launch.

If memory is the issue, stopping a heavy app or restarting the server often clears it. If space is the issue, the fix is to free room or add storage - we cover a full cache on the next pages.

• On the Dashboard, look at the memory (RAM) gauge - is it pinned near full?
• Check the cache and array space - a full cache drive stops apps cold.
• Look for one app using far more memory than the rest.
• A recent big download or backup can fill space quietly.

The App's Own Settings Are Wrong

Sometimes the container starts fine, then the app inside stops itself because one of its own settings is off - a wrong password, a missing key, a database it cannot reach. This is different from Unraid's settings; it is the app's own.

The log is your friend here. It will often say what it wanted and could not get: "cannot connect to database," "invalid API key," "configuration error." That points you straight at the setting to fix.

• On the Edit page, look at the "variables" - these are the app's own settings Unraid passes in.
• Inside the app itself, there is often a config file in its appdata folder.
• A recent change you made - a new password, a moved folder - is the usual culprit.

Forcing An Update Or Re-Pulling The Image

Re-pulling means telling Unraid to download the app's program files fresh. If the current copy is half-broken, a clean download often fixes it. This is safe - it does not touch your settings or data in appdata.

After it finishes, watch whether the app starts and stays running. Give it a minute - some apps take a moment to wake up the first time after an update.

• Go to the Docker tab.
• Look for a "Check for Updates" link at the bottom of the container list.
• If an update shows, click to apply it.
• If no update shows but you want a clean copy, use the app's Edit page and re-apply, which re-pulls the image.

Reinstall From "Previous Apps"

This is the safe reset. "Previous Apps" remembers how an app was set up. Reinstalling from there gives you a fresh, clean container while keeping your appdata - so your settings and data come right back.

Because appdata is left alone, a media app finds its library again, a download app finds its history, and so on. This fixes a surprising number of "won't start" cases where the container itself got tangled.

• Open the Apps tab (Community Applications).
• Look for "Previous Apps" - it lists apps you have installed before.
• Find the stuck app and choose to reinstall it.
• Its old settings load in - review them, then apply.
• Start it and watch the log to confirm it is happy.

Check The Cache And appdata Aren't Full

Most apps keep their appdata on the cache drive (usually an SSD) because it is fast. If that cache drive fills up, apps that live on it cannot start. This one catches a lot of people.

Unraid has a "Mover" that shifts files from cache to the array on a schedule. Running the Mover can free cache space. You can also point space-hungry downloads at the array instead of the cache. If the cache is simply too small, a bigger cache drive is the real fix.

• On the Dashboard or Main tab, look at the cache drive's used space.
• If it is near full, that is very likely your problem.
• A large download, a backup, or lots of app data can quietly fill it.

Internet Or DNS Trouble For The App

Some apps need to reach the internet to start - to check a login, download a list, or talk to a service. If the server's internet or its "DNS" (the internet's phone book) is having trouble, those apps can stall.

In the log you might see "could not resolve host," "connection timed out," or "network unreachable." That points at the connection, not the app itself.

• Confirm the server has internet - other apps that use the web will also struggle if not.
• In Unraid's network settings, check that a DNS server is set (many people use a reliable public one).
• Restart the container after any network change.
• If you use a VPN container, a stuck VPN can block apps routed through it.

A Container It Depends On Is Down

Some apps lean on another app to work. A photo or media app might need a separate database container. A download manager might need a VPN container. If the helper is down, the main app cannot start.

The log often names the missing partner: "cannot connect to database," or the app waiting forever for something that never answers. The fix is to get the helper running first.

• List which apps work together - a database, a VPN, a reverse proxy.
• Start the helper container first, confirm it is healthy.
• Then start the main app and watch its log.
• If the helper also won't start, fix it the same careful way - it is just another container.

A Typo In The Template

Every app's setup lives in a "template" - the page of fields you filled in when installing. A single typo there - a stray space, a wrong number, a mismatched folder - can stop the app from starting.

This is especially likely if the app broke right after you edited its settings. The container is doing exactly what you told it; it is just that what you told it has a small mistake.

• Open the app's Edit page and read each field slowly.
• Look for extra spaces at the start or end of a value.
• Check that ports are numbers and folders point to real places.
• Confirm any passwords or keys match what the app expects, character for character.

Where To Get That App's Support

Each app is made by different people, and they usually run the best help for it. When your log shows an error you cannot place, the app maker's own support is where to take it.

When you ask for help, share the exact error from the log, what you already tried, and what changed just before it broke. That gets you a good answer far faster than "it won't start."

• The app's page in Community Applications often has a "Support" link.
• That link usually goes to the Unraid forum thread for that app.
• Many apps also have their own website, wiki, or documentation.
• Search the exact error line - odds are someone hit it before you.

When To Restore An appdata Backup

If the app's settings have gotten genuinely tangled - not just a stuck container, but corrupted settings - restoring a backup of appdata can bring it back to a known-good state. This is why we back up appdata in the first place.

Many folks run the "Appdata Backup" plugin, which saves a copy of appdata on a schedule. If you have one, you can roll a troubled app back to how it was before the trouble started.

• Stop the app first so nothing is writing to appdata.
• Restore only that app's appdata folder from your backup, not everything.
• Pick a backup from before the problem began.
• Start the app and confirm it comes up healthy.

When To Stop And Call For Help

You can handle most of this yourself with patience. But there is no prize for struggling alone, and some signs mean it is smarter to get a second set of eyes before you make things worse.

Calling early is cheaper than calling after a hasty deletion. When in doubt, take your hands off the keyboard and describe what you see. Half the battle is knowing which problem you actually have.

• The log points at a drive problem, not just the app - stop and get help.
• You are being tempted to delete folders to "just start over."
• Several apps failed at once, which can point at storage or the server itself.
• You have tried the safe fixes and are no longer sure what you are changing.

What's in the 27-page PDF

• How to stay calm and work in order
• Reading the container's log to see the real problem
• The common causes, one page at a time
• Safe fixes: re-pulling, reinstalling, restoring a backup
• Where to get support for a specific app
• When to stop and call me

Why I wrote this

I write these as printable handouts because a guide you can keep in a drawer beats a web page you have to find again. No jargon, no judgment, no rushing. If you'd rather have someone sit beside you and go through it together, that's a flat $99 first visit with the 30-day follow-up included — serving Portage County from Atwater, Ohio. — Bill