Skip to content

fix: improve port conflict detection by enhancing error messages and …#3940

Merged
Siumauricio merged 1 commit intocanaryfrom
3806-bug-traefik-and-dokploy-fails-to-start-when-port-8080-is-already-in-use-service-crash
Mar 8, 2026
Merged

fix: improve port conflict detection by enhancing error messages and …#3940
Siumauricio merged 1 commit intocanaryfrom
3806-bug-traefik-and-dokploy-fails-to-start-when-port-8080-is-already-in-use-service-crash

Conversation

@Siumauricio
Copy link
Contributor

@Siumauricio Siumauricio commented Mar 8, 2026

…adding host-level service checks

What is this PR about?

Please describe in a short paragraph what this PR is about.

Checklist

Before submitting this PR, please make sure that:

  • You created a dedicated branch based on the canary branch.
  • You have read the suggestions in the CONTRIBUTING.md file https://github.com/Dokploy/dokploy/blob/canary/CONTRIBUTING.md#pull-request
  • You have tested this PR in your local instance. If you have not tested it yet, please do so before submitting. This helps avoid wasting maintainers' time reviewing code that has not been verified by you.

Issues related (if applicable)

closes #3806

Screenshots (if applicable)

Greptile Summary

This PR improves port conflict detection in checkPortInUse by (1) moving the quoted container-name formatting into the return value itself, and (2) adding a second host-level probe via an ephemeral docker run --rm --net=host busybox nc -z container to catch non-Docker services that may already occupy a port.

Key changes:

  • packages/server/src/services/settings.ts: checkPortInUse now runs a two-stage check — first Docker containers (excluding dokploy-traefik), then a host-network nc -z probe for any remaining listeners.
  • apps/dokploy/server/api/routers/settings.ts: Error message construction is updated to match the new string format returned by checkPortInUse.

Issue found:

  • The host-level nc -z probe does not account for dokploy-traefik being excluded from the Docker check. If Traefik itself is already listening on the target port, the probe will misreport it as "a host-level service", producing a misleading conflict error when users try to reconfigure existing Traefik ports.

Confidence Score: 3/5

  • The PR is mostly safe but introduces a logic gap where Traefik's own ports can trigger a misleading conflict error.
  • The Docker-container check path is unchanged and correct. The new host-level probe adds useful detection for non-Docker services. However, there is a concrete logic bug where Traefik (which is explicitly excluded from the Docker check) can be misidentified as a "host-level service" when reconfiguring its own ports, potentially blocking legitimate operations with a confusing UX.
  • packages/server/src/services/settings.ts — specifically the checkPortInUse function logic around the Traefik exclusion

Last reviewed commit: ce82e23

Greptile also left 1 inline comment on this PR.

Context used:

  • Rule used - AGENTS.md (source)

@dosubot dosubot bot added the size:M This PR changes 30-99 lines, ignoring generated files. label Mar 8, 2026
@Siumauricio Siumauricio merged commit 8e9ab98 into canary Mar 8, 2026
5 checks passed
@Siumauricio Siumauricio deleted the 3806-bug-traefik-and-dokploy-fails-to-start-when-port-8080-is-already-in-use-service-crash branch March 8, 2026 09:09
@dosubot dosubot bot added the bug Something isn't working label Mar 8, 2026
Comment on lines +431 to +445
// Check if port is in use by a host-level service (non-Docker)
// Dokploy runs inside a container, so we spawn an ephemeral container
// with --net=host to share the host's network stack and use nc -z to
// check if something is listening on the port
const hostCommand = `docker run --rm --net=host busybox sh -c 'nc -z 0.0.0.0 ${port} 2>/dev/null && echo in_use || echo free'`;
const { stdout: hostOut } = serverId
? await execAsyncRemote(serverId, hostCommand)
: await execAsync(hostCommand);

if (hostOut.includes("in_use")) {
return {
isInUse: true,
conflictingContainer: "a host-level service",
};
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Host check false-positive against Traefik's own ports

The Docker check explicitly excludes dokploy-traefik via grep -v '^dokploy-traefik$' on line 417, but the subsequent nc -z host-level check has no awareness of this exclusion. If Traefik is already running and listening on a port (e.g., 8080 for the dashboard), the Docker check will skip Traefik and find no container conflict, then the host check will detect the open port and return { isInUse: true, conflictingContainer: "a host-level service" }.

The result is a misleading error message: when a user tries to enable the Traefik dashboard on an already-configured port, they are told the port is occupied by "a host-level service" when the actual occupant is Traefik itself.

Consider checking whether dokploy-traefik is already listening on the target port (e.g., by querying its port mappings) and skipping the host-level check if it is, or unifying the exclusion logic so the host check is also aware of Traefik.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working size:M This PR changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] Traefik (and dokploy) fails to start when port 8080 is already in use (Service Crash)

1 participant