NAS Codex › QNAP › QNAP Container Station container won't start

QNAP Container Station container won't start

When a Docker or LXD container in Container Station fails to deploy, won't start, or exits right after starting, QNAP's troubleshooting tutorial works through the same checks in order: the image's own requirements, the Container Station event logs, the container's logs, image compatibility, and the NAS's own settings. QNAP notes that it does not provide technical support for third-party images.

Written against: Container Station 3 and later on QTS and QuTS hero (QNAP tutorial last modified 2025-04-08; QNAP FAQs last modified 2023-04-27 and 2025-08-27). Last Updated: November 2026. Vendor menus and wording change between versions; if yours differ, follow the vendor page linked under Sources.

Before anything else: if the data on this NAS is not backed up somewhere else, copy it off first. Do not continue with any step on this page until you have.

Fast Answer

Open Container Station > Event Logs and the container's own Logs tab: QNAP says failure entries name the container, the error code and the details. Common causes it shows are a port already in use, a missing required environment variable, a wrong entrypoint, an image built for a different CPU architecture (exec format error), and container networks missing from the NAS allow list.

1. Check what the image needs

QNAP says containers inherit all attributes of the source image, so review the image's prerequisites before deploying. To see an image's details, click its name in Explore > Docker Hub in Container Station, or search for it on Docker Hub. QNAP's example: a PostgreSQL container made from the postgres image fails to deploy unless the POSTGRES_PASSWORD environment variable is set in the Environment section.

2. Read the Container Station event logs

Container Station logs all application and container activity, and QNAP says failure logs give the application or container name, an error code and error details. Open Container Station, click Event Logs and find the failure entries. QNAP's two examples are a startup failure because the specified ports were already used by other services, and a startup failure caused by a misconfigured entrypoint command.

3. Read the container's own logs

In Container Station, click Containers, select the container to open its details page, click Logs and review the error and warning messages. QNAP says these show problems such as missing environment variables, invalid naming formats, failed image retrievals and initialization failures. Its examples: a MySQL container that exits right after initialization because MYSQL_ROOT_PASSWORD was not set, and a Rancher container that could not initialize because it was deployed from the rancher/rancher image without privileged mode (--privileged).

4. Check that the image fits the NAS

QNAP says the image must match the NAS's processor architecture. 64-bit x86 images can't run on 64-bit or 32-bit ARM devices, and ARM images can't run on 64-bit x86 devices. If you move an image from another QNAP device, confirm both use the same architecture.

QNAP also changed the system page size from 4K to 32K on some 32-bit ARM models, which can limit a container's memory access and cause segmentation faults. The series it lists are TS-x31P, TS-x31P3, TS-x31X, TS-x31KX, TS-x31XU, TS-x31XeU and TS-x35 (TS-1635). Check a third-party container's compatibility before deploying it on those models.

5. Check the NAS's allow list

  1. Open Network & Virtual Switch, select Advanced mode, go to Network > Virtual Switch and note the network segments the container network uses.
  2. Go to Control Panel > System > Security > Allow/Deny List and make sure those segments are on the allow list. If QuFirewall is installed, make sure it is enabled and add the segments to its allow list.

QNAP strongly recommends allowing the Container Station ranges 10.0.3.0/24, 10.0.5.0/24, 10.0.7.0/24, 172.29.0.0/22 and 172.30.0.0/22, plus 10.42.0.0/24 (the Kubernetes Pod Network CIDR) if Kubernetes is enabled.

6. Check permissions and quota

QNAP says containers run directly on the system and share root privileges with the host, and advanced folder permissions can affect them. If a container fails to run, go to Control Panel > Privilege > Shared Folders > Advanced Permissions, turn off Enable Advanced Folder Permissions and click Apply. Then check Control Panel > Privilege > Quota: QNAP warns that an accidental quota setting can make a container report errors from storage limits.

7. Check storage and network settings

8. After upgrading to Container Station 5.0.1.2145

QNAP says newer Container Station versions, from 5.0.1.2145, require network information such as the default gateway for containers in Bridge mode. If a Docker container won't start after that upgrade: open Container Station, click the container name on the Overview page, click Settings, go to Advance setting > Network, set Network Mode to Bridge, and under Use Interface choose the virtual switch that connects to the network. QNAP notes it must be a virtual switch with an assigned IP address (static or from a DHCP client). Check the settings in Network & Virtual Switch, then start the container.

When to stop and get help

If none of these checks fix it, QNAP says the source image may be incompatible or corrupted, and recommends the image's own website or an alternative image in the same category. QNAP does not provide technical support for third-party images.

Questions

Why does my QNAP Container Station container exit right after starting?

QNAP's examples include a required environment variable that was not set, such as MYSQL_ROOT_PASSWORD, and an image that needs privileged mode. Check the container's Logs tab.

What does exec format error mean in Container Station?

QNAP says an incompatible Docker container may log exec format error, meaning the image's architecture doesn't match the NAS, for example an x86 image on an ARM model.

Which networks should I allow for QNAP Container Station?

QNAP recommends allowing 10.0.3.0/24, 10.0.5.0/24, 10.0.7.0/24, 172.29.0.0/22 and 172.30.0.0/22, plus 10.42.0.0/24 if Kubernetes is enabled.

Sources

Every fact on this page comes from the vendor documents below, opened on 2026-11-17.