Portainer integration: Timeout on setup due to slow docker system df on NAS/overlay filesystems

[groovyM]

The problem

Describe the bug

The Portainer integration fails with a recurring setup_retry / setup_error state because
the API call to GET /api/endpoints/{id}/docker/system/df times out on systems where
docker system df is structurally slow — specifically NAS devices (Synology, QNAP, etc.)
running Docker on an overlay filesystem.

The integration connects successfully and authenticates correctly (token is valid), but fails
during setup when fetching disk usage data.

Error message

Einrichtungsfehler, wird erneut versucht: Timeout error while accessing 
GET http://192.168.x.x:9000/api/endpoints/2/docker/system/df:

Steps to reproduce

1. Install Portainer (CE, latest) on a Synology NAS (DS1621+ or similar)
2. Configure the Portainer integration in Home Assistant
3. Integration cycles between setup_in_progress → setup_error → setup_retry

Root cause

docker system df on overlay filesystems (as used by Synology DSM Docker) is inherently slow.
It scans all image layers, containers, and volumes.

Measured on affected system:

$ time docker system df
TYPE       TOTAL   ACTIVE   SIZE      RECLAIMABLE
Images     13      13       14.84GB   157.2MB
Containers 13      13       1.143GB   0B
Volumes    1       1        4.542MB   0B

real  0m17.65s

The integration's HTTP timeout is shorter than 17+ seconds, causing every setup attempt to fail.

Environment

• Home Assistant version: 2026.3.1
• Portainer version: CE latest (2.x)
• Portainer host: Synology DS1621+ (DSM 7.x), Docker on overlay filesystem
• Portainer accessible: Yes (API responds, token valid, containers visible via direct API calls)
• Integration state: Cycles setup_in_progress → setup_error → setup_retry

Suggested fix

One or more of the following:

1. Make the timeout configurable — allow users to set a custom timeout for the
   docker/system/df call in the integration options (e.g. default 30s, configurable up to 120s)

2. Skip docker/system/df during setup — fetch disk usage only during polling updates,
   not during the initial setup phase where a timeout causes a full setup failure

3. Make disk usage sensors optional — allow the integration to complete setup without
   disk usage data, and mark those sensors as unavailable if the call fails/times out

Additional context

The integration works correctly in terms of authentication and container data.
Direct API calls to /api/endpoints/2/docker/containers/json respond instantly.
Only the system/df endpoint is problematic due to filesystem characteristics of the host.

What version of Home Assistant Core has the issue?

Home Assistant version:** 2026.3.1

What was the last working version of Home Assistant Core?

No response

What type of installation are you running?

Home Assistant OS

Integration causing the issue

No response

Link to integration documentation on our website

No response

Diagnostics information

No response

Example YAML snippet

Anything in the logs that might be useful for us?

Additional information

No response

[brstgt]

I suggest to make the df completely optional. I have the same issue. The portainer integration became completely useless for me. Absolutely disfunctional since this change!

[groovyM]

During the reconfiguration, I unchecked the SSL checkbox for the Portainer integration in HA. It worked immediately.