Skip to content

setkeepalive < 1000 silently ignored #57712

Open
Open
setkeepalive < 1000 silently ignored#57712
Labels
docIssues and PRs related to Node.js documentation.netIssues and PRs related to the net subsystem.

Description

@rotu
rotu
opened on Apr 1, 2025

Version

22.14.0

Platform

N/A

Subsystem

No response

What steps will reproduce the bug?

Create a TCP socket and call socket.setKeepAlive(true, 400).

How often does it reproduce? Is there a required condition?

Any keepalive less than 1 second.

What is the expected behavior? Why is that the expected behavior?

This should send keepalive packets every 400 ms.

The documentation says as much:

keepAliveInitialDelay {number} If set to a positive number, it sets the
initial delay before the first keepalive probe is sent on an idle socket.
Default: 0.

What do you see instead?

The code truncates to the nearest 1000ms, so the socket doesn't send keepalive packets and no error is issued.

Additional information

It seems this parameter is even broken in the tests.

node/test/parallel/test-net-keepalive.js

Line 42 in 3db5491

connection.setKeepAlive(true, common.platformTimeout(50));

node/test/parallel/test-net-persistent-keepalive.js

Line 30 in 3db5491

const s = clientConnection.setKeepAlive(true, 400);

Ideally, the keepalive interval would be respected in milliseconds. Assuming that's infeasible,

  1. a runtime warning should be issued if setKeepAlive is given a value <1000.
  2. the documentation should be updated to reflect that, even though the value is given in milliseconds, it will only be respected to the second.

Activity

  1. Emill commented on Sep 4, 2025

    @Emill
    Emill
    on Sep 4, 2025

    Linux has the requirement that the initial delay must be an integer number of seconds >= 1 and <= 32767, otherwise EINVAL is returned from the kernel. I suggest the millisecond parameter is rounded up to the nearest second. If the number is instead rounded down, the probe is sent earlier than the user instructed. However, it should be capped at 32767. Now an invalid value is silently ignored.

  2. Emill commented on Sep 4, 2025

    @Emill
    Emill
    on Sep 4, 2025

    Also, the current optional parameter handling doesn't seem to match the documentation. Current code:

    node/lib/net.js

    Lines 626 to 628 in 538186b

    Socket.prototype.setKeepAlive = function(enable, initialDelayMsecs) {
    enable = Boolean(enable);
    const initialDelay = ~~(initialDelayMsecs / 1000);

    The documentation says socket.setKeepAlive([enable][, initialDelay]).

    So, e.g. updating to 3 seconds by calling socket.setKeepAlive(3000) doesn't work.

  3. yoshigev commented on Mar 4, 2026

    @yoshigev
    yoshigev
    on Mar 4, 2026

    We also hit this problem. I think the documentation should be fixed to mention this.

  4. efekrskl commented on Mar 9, 2026

    @efekrskl
    efekrskl
    on Mar 9, 2026
    Member

    As far as I see libuv uses seconds for this value and any value below 1 returns an error code, so I think the current behaviour makes sense. However, I agree the silent truncation can be confusing. I opened a PR to improve the docs

  5. efekrskl
    added
    docIssues and PRs related to Node.js documentation.
    netIssues and PRs related to the net subsystem.
    on Mar 9, 2026

  6. khalidsaidi commented on Mar 25, 2026

    @khalidsaidi
    khalidsaidi
    on Mar 25, 2026 · Hidden as off-topic

  7. efekrskl commented on Jun 16, 2026

    @efekrskl
    efekrskl
    on Jun 16, 2026
    Member

    #63825 significantly improved the docs for socket.setKeepAlive and mentions the rounding down behaviour. Can we close this?

  8. rotu commented on Jun 17, 2026

    @rotu
    rotu
    on Jun 17, 2026
    Author

    @efekrskl The docs are a step in the right direction, but I still think a runtime warning is warranted.

  9. zeexzeex
    added 3 commits that reference this issue on Sep 4, 2026

    net: warn on keep-alive delays truncated to zero

    cc29daa

    net: reject keep-alive delays that cannot be applied

    e36ca60

    net: reject keep-alive delays that cannot be applied

    6222f2f

  10. github-actions commented on Sep 16, 2026

    @github-actions
    github-actionsbot
    on Sep 16, 2026 – with GitHub Actions
    Contributor

    This issue has been marked as stale due to 90 days of inactivity.
    It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

  11. github-actions
    added
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on Sep 16, 2026

  12. rotu commented on Sep 16, 2026

    @rotu
    rotu
    on Sep 16, 2026
    Author

    unstale

  13. efekrskl
    removed
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on Sep 16, 2026
  14. nodejs-github-bot
    added a commit that references this issue on Sep 18, 2026

    doc: clarify sub-1000ms behavior in socket.setKeepAlive

    7c01b98
  15. aduh95
    added 3 commits that reference this issue on Sep 18, 2026

    doc: clarify sub-1000ms behavior in socket.setKeepAlive

    317abb8

    doc: clarify sub-1000ms behavior in socket.setKeepAlive

    2d42b03

    doc: clarify sub-1000ms behavior in socket.setKeepAlive

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    docIssues and PRs related to Node.js documentation.netIssues and PRs related to the net subsystem.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions