Skip to content

docs: document EWS03 and EIF01 health codes and guard against undocumented codes - #31808

Closed
coder[bot] wants to merge 2 commits into
mainfrom
docs/health-codes-ews03-eif01
Closed

coder[bot] wants to merge 2 commits into
mainfrom
docs/health-codes-ews03-eif01

Conversation

@coder

@coder coder Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Two health codes, EWS03 and EIF01, are emitted at runtime but had no section in the health check docs. health.Message.URL links to admin/monitoring/health-check#<lowercased code>, so operators who hit either code followed a link to an anchor that did not exist.

Changes:

  • docs/admin/monitoring/health-check.md: adds an EWS03 section (the WebSocket echo reply had the wrong message type or contents) under Websocket. Adds a new "Network interfaces" section with EIF01 (an interface MTU below 1378). Both use the existing ### CODE / #### Title / Problem / Solution format, and the prose is hand-written.
  • coderd/healthcheck/health/docs_test.go: adds TestCodesDocumented. It reads every Code* constant from model.go, so new codes are covered without editing the test, including untyped ones like EIF01 and ESTUN01. It builds each code's link with health.Message{Code: ...}.URL("") and fails if the fragment does not match a heading anchor on the page. Headings inside fenced code blocks are ignored. It runs in the normal Go test suite in CI. Without the new docs sections it fails for exactly EIF01 and EWS03.

Checks run: go test ./coderd/healthcheck/health/, golangci-lint on the package, make pre-commit (includes markdownlint, docs-html, docs-manifest, docs-redirects and emdash), and make lint/prose. The remaining Vale suggestions on the page are all on lines this PR does not change.

Verified against:

  • coderd/healthcheck/health/model.go (code constants and Message.URL anchor construction)
  • coderd/healthcheck/websocket.go (EWS03 emission, echo against /api/v2/debug/ws)
  • codersdk/healthsdk/interfaces.go (EIF01 emission, safeMTU = 1378, filtering of interfaces that are down, have no addresses, or have only link-local addresses, warning severity)
  • cli/ping.go, cli/netcheck.go, cli/cliui/agent.go, agent/health.go, support/support.go (where the interface report appears)
  • docs/admin/networking/troubleshooting.md#low-mtu and docs/reference/cli/server/index.md#--block-direct-connections (link targets)

Open questions for the reviewer:

  • EIF01 does not appear on the deployment health page. Only coder ping, coder netcheck and support bundles report it. I documented it on the health check page under a new "Network interfaces" section with a note explaining this, because Message.URL always links to that page. Is that placement acceptable?
  • The EWS03 causes (a proxy, load balancer or traffic inspection device changing WebSocket messages, or the Access URL routing to a different service) are inferred from what the check does. No field reports confirm them. A networking SME may want to confirm or refine them.
  • The anchor check uses GitHub-style heading slugs. Please confirm the coder.com docs site makes the same slugs for these simple ### CODE headings. The existing #eacs03 links suggest it does.

Generated by Coder Agents.

Closes DOCS-910

…ented codes

Add remediation sections for EWS03 (unexpected WebSocket message) and
EIF01 (low network interface MTU) to the health check page, and add a
test that fails when a health code constant has no heading matching the
anchor that health.Message.URL links to.
@coder
coder Bot requested a review from nickvigilante November 5, 2026 20:35
@linear-code

linear-code Bot commented Nov 5, 2026

Copy link
Copy Markdown

DOCS-910

@github-actions github-actions Bot added the community Pull Requests and issues created by the community. label Nov 5, 2026
Comment thread docs/admin/monitoring/health-check.md Resolved
@nickvigilante
nickvigilante temporarily deployed to main November 9, 2026 21:55 — with GitHub Actions Inactive
@nickvigilante
nickvigilante marked this pull request as ready for review November 9, 2026 21:56
@nickvigilante
nickvigilante temporarily deployed to main November 9, 2026 21:56 — with GitHub Actions Inactive

## Network interfaces

The network interface check inspects the network interfaces of the machine it runs on, not the Coder server.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Continuity Editor) the Coder server is not the canonical term for the component that serves the Coder API and dashboard; the word-choice rule bans it in favor of control plane. The same page uses control plane at line 227, so this reads inconsistently.

Rule: docs/.style/style-guide/word-choice.md#naming-coders-components

Suggested change
The network interface check inspects the network interfaces of the machine it runs on, not the Coder server.
The network interface check inspects the network interfaces of the machine it runs on, not the control plane.

A network interface that is up and has a non-link-local address has a maximum transmission unit (MTU) smaller than 1378.
Direct connections over this interface might have degraded quality or might hang entirely.
This is a warning.
Connections relayed through DERP are not affected.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Copy Editor) This is a statement, not a negative instruction, so the default contraction applies. are not should be aren't.

Rule: docs/.style/style-guide/voice-and-tone.md#contractions-are-the-default

Suggested change
Connections relayed through DERP are not affected.
Connections relayed through DERP aren't affected.

Connections relayed through DERP are not affected.

**Solution:**
Increase the MTU of the affected interface to 1378 or higher, or use a different network interface.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Copy Editor) A comma appears before or joining two verbs (Increase and use) that share one subject. The no-comma-in-a-short-compound-predicate rule applies. Consider splitting it.

Rule: docs/.style/style-guide/capitalization-and-punctuation.md#no-comma-in-a-short-compound-predicate

Suggested change
Increase the MTU of the affected interface to 1378 or higher, or use a different network interface.
Increase the MTU of the affected interface to 1378 or higher. If you can't, use a different network interface.


**Solution:**
Increase the MTU of the affected interface to 1378 or higher, or use a different network interface.
Virtual private network (VPN) tunnel interfaces often have a low MTU.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Copy Editor) often is a vague qualifier named by the weasel-words rule; it says the statement is sometimes false without saying when. Remove it and state the claim as a default.

Rule: docs/.style/style-guide/word-choice.md#avoid-weasel-words

Suggested change
Virtual private network (VPN) tunnel interfaces often have a low MTU.
Virtual private network (VPN) tunnel interfaces have a low MTU.

Virtual private network (VPN) tunnel interfaces often have a low MTU.

If you can't change the MTU or use another interface, you can block direct connections so that all traffic is relayed through DERP.
To do this, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Copy Editor) To do this is a bare this that summarizes the preceding clause; name the thing it refers to.

Rule: docs/.style/style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent

Suggested change
To do this, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane.
To block direct connections, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane.

#### Received an unexpected WebSocket message

**Problem:**
Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Copy Editor) This is a statement, not a negative instruction, so the default contraction applies. did not match should be didn't match.

Rule: docs/.style/style-guide/voice-and-tone.md#contractions-are-the-default

Suggested change
Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match.
Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply didn't match.

**Problem:**
Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match.
Either the reply was not a text message, or its contents differ from the message Coder sent.
This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Copy Editor) This can happen uses a bare this that summarizes a whole clause; name the thing it refers to.

Rule: docs/.style/style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent

Suggested change
This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder.
This mismatch can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL doesn't route to Coder.

**Problem:**
Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match.
Either the reply was not a text message, or its contents differ from the message Coder sent.
This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: (Copy Editor) does not route is a statement, so the default contraction applies. Should be doesn't route.

Rule: docs/.style/style-guide/voice-and-tone.md#contractions-are-the-default

Suggested change
This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder.
or when the Access URL doesn't route to Coder.

#### Network interface has a low MTU

**Problem:**
A network interface that is up and has a non-link-local address has a maximum transmission unit (MTU) smaller than 1378.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

(Fact Checker) The trigger description omits the code's iface.MTU > 0 guard, so it would also describe interfaces with MTU 0 or negative (the code explicitly skips a negative MTU on Windows loopback). The guard is not pinned by a test. Suggest adding a test case in codersdk/healthsdk/interfaces_internal_test.go asserting an up interface with a non-link-local address and MTU <= 0 does not produce an EIF01 warning, and consider qualifying the doc with greater than 0.


**Problem:**
Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match.
Either the reply was not a text message, or its contents differ from the message Coder sent.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

(Fact Checker) The two conditions that produce EWS03 are pinned only by coderd/healthcheck/websocket.go:90-100; websocket_test.go never exercises the message-type or content-mismatch path. Suggest a TestWebsocket sub-test that returns a different message type or different contents, asserting CodeWebsocketMsg and SeverityError.

@coderagents

coderagents Bot commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Blocking

  • docs/admin/monitoring/health-check.md (open) - "the Coder server" should be "control plane" (word-choice rule); the page already uses "control plane" at line 227
  • docs/admin/monitoring/health-check.md (open) - "Connections relayed through DERP are not affected." should use the contraction "aren't"
  • docs/admin/monitoring/health-check.md (open) - "Increase the MTU ... or use a different network interface." has a comma before "or" joining two verbs sharing a subject
  • docs/admin/monitoring/health-check.md (open) - "VPN tunnel interfaces often have a low MTU." uses the vague qualifier "often"
  • docs/admin/monitoring/health-check.md (open) - "To do this, set the ..." has a bare "this" pronoun; the referent is the preceding clause
  • docs/admin/monitoring/health-check.md (open) - EWS03 problem text narrates the internal echo-comparison mechanism the reader never sees or types
  • docs/admin/monitoring/health-check.md (open) - "the reply did not match" should use the contraction "didn't"
  • docs/admin/monitoring/health-check.md (open) - "This can happen when ..." has a bare "this" pronoun
  • docs/admin/monitoring/health-check.md (open) - "the Access URL does not route to Coder" should use the contraction "doesn't"

New documentation needed

None.

Design notes

  • The EWS03 section does not label its severity, while the EIF01 section explicitly says "This is a warning." The page omits severity for most codes (only EIF01 and ESTUN02 state it), so this is consistent with the page, but it leaves an operator unable to tell error from warning on the WebSocket echo check.

Related open PRs

Findings for agents
- id: consistency-1
  persona: consistency
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 208
  quote: "The network interface check inspects the network interfaces of the machine it runs on, not the Coder server."
  evidence:
    - docs/.style/style-guide/word-choice.md:158
    - docs/admin/monitoring/health-check.md:227
  rule: word-choice.md#naming-coders-components
  problem: The new section names the server component "the Coder server", the term the word-choice rule bans in favor of "control plane".
  fix: "The network interface check inspects the network interfaces of the machine it runs on, not the control plane."
  verified: true
- id: language-2
  persona: language
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 220
  quote: "Connections relayed through DERP are not affected."
  evidence:
    - docs/.style/style-guide/voice-and-tone.md:245
  rule: voice-and-tone.md#contractions-are-the-default
  problem: This is a statement, not a negative instruction, so the default contraction applies.
  fix: "Connections relayed through DERP aren't affected."
  verified: true
- id: language-3
  persona: language
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 223
  quote: "Increase the MTU of the affected interface to 1378 or higher, or use a different network interface."
  evidence:
    - docs/.style/style-guide/capitalization-and-punctuation.md:160
  rule: capitalization-and-punctuation.md#no-comma-in-a-short-compound-predicate
  problem: A comma appears before "or" joining two verbs that share one subject.
  fix: "Increase the MTU of the affected interface to 1378 or higher. If you can't, use a different network interface."
  verified: true
- id: language-4
  persona: language
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 224
  quote: "Virtual private network (VPN) tunnel interfaces often have a low MTU."
  evidence:
    - docs/.style/style-guide/word-choice.md:578
  rule: word-choice.md#avoid-weasel-words
  problem: "often" is a vague qualifier that says the statement is sometimes false without saying when.
  fix: "Virtual private network (VPN) tunnel interfaces have a low MTU."
  verified: true
- id: language-5
  persona: language
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 227
  quote: "To do this, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane."
  evidence:
    - docs/.style/style-guide/voice-and-tone.md:222
  rule: voice-and-tone.md#give-each-pronoun-one-clear-referent
  problem: "this" is a bare pronoun that summarizes the preceding clause.
  fix: "To block direct connections, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane."
  verified: true
- id: audience-1
  persona: audience
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 279
  quote: "Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match. Either the reply was not a text message, or its contents differ from the message Coder sent."
  evidence:
    - coderd/healthcheck/websocket.go:90-100
    - docs/admin/monitoring/health-check.md:240
  rule: docs/.style/content-guidelines.md#describe-the-current-version-for-the-end-user
  problem: This narrates the internal echo-comparison mechanism, which the reader never sees, types, or acts on; the page already established the echo check at line 240.
  fix: "Coder established a WebSocket connection over its own Access URL, but the message it read back did not match what it sent. This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder."
  verified: true
- id: language-6
  persona: language
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 279
  quote: "Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match."
  evidence:
    - docs/.style/style-guide/voice-and-tone.md:245
  rule: voice-and-tone.md#contractions-are-the-default
  problem: This is a statement, not a negative instruction, so the default contraction applies.
  fix: "Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply didn't match."
  verified: true
- id: language-7
  persona: language
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 281
  quote: "This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder."
  evidence:
    - docs/.style/style-guide/voice-and-tone.md:222
  rule: voice-and-tone.md#give-each-pronoun-one-clear-referent
  problem: "this" is a bare pronoun that summarizes the preceding clause.
  fix: "This mismatch can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL doesn't route to Coder."
  verified: true
- id: language-8
  persona: language
  class: rule
  blocking: true
  file: docs/admin/monitoring/health-check.md
  line: 281
  quote: "or when the Access URL does not route to Coder."
  evidence:
    - docs/.style/style-guide/voice-and-tone.md:245
  rule: voice-and-tone.md#contractions-are-the-default
  problem: This is a statement, so the default contraction applies.
  fix: "or when the Access URL doesn't route to Coder."
  verified: true
- id: accuracy-1
  persona: accuracy
  class: suggestion
  blocking: false
  file: docs/admin/monitoring/health-check.md
  line: 217
  quote: "A network interface that is up and has a non-link-local address has a maximum transmission unit (MTU) smaller than 1378."
  evidence:
    - codersdk/healthsdk/interfaces.go:73
    - codersdk/healthsdk/interfaces.go:71-72
    - codersdk/healthsdk/interfaces.go:16
  rule: null
  problem: The trigger description omits the code's iface.MTU > 0 guard, so it would also describe interfaces with MTU 0 or negative that the check skips.
  fix: Add a test in codersdk/healthsdk/interfaces_internal_test.go asserting an up interface with a non-link-local address and MTU <= 0 does not produce an EIF01 warning; optionally qualify with "greater than 0".
  verified: true
- id: accuracy-2
  persona: accuracy
  class: suggestion
  blocking: false
  file: docs/admin/monitoring/health-check.md
  line: 280
  quote: "Either the reply was not a text message, or its contents differ from the message Coder sent."
  evidence:
    - coderd/healthcheck/websocket.go:90-100
    - coderd/healthcheck/websocket_test.go:19-91
  rule: null
  problem: The two conditions that produce EWS03 are pinned only by websocket.go; websocket_test.go never exercises the message-type or content-mismatch path.
  fix: Add a TestWebsocket sub-test returning a different message type or different contents, asserting CodeWebsocketMsg and SeverityError.
  verified: true

Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.

@nickvigilante

Copy link
Copy Markdown
Collaborator

Closing and reopening under a human author, as required for this repository.

@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 10, 2026

This branch was previously deployed

1 inactive deployment
main — 5fcbdace Deployed Nov 10, 2026 by nickvigilante via community-label #253434
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants