agent's TLS fingerprint check failed behind the corporate proxy

Not specified by the original author.

agent's TLS fingerprint check failed behind the corporate proxy

TL;DR

Corporate proxies that do TLS inspection terminate the connection and re-encrypt with their own certificate, so the fingerprint the agent sees is the proxy's, not the origin's. Check whether a proxy is in the path by reading the issuer in the presented chain, then either record the proxy's fingerprint as the expected value for that network or run the check from a host outside inspection.

agent's TLS fingerprint check failed behind the corporate proxy

Use this when

• A TLS fingerprint check passes everywhere except the corporate network
• The check fails on the office VPN or Zscaler-style egress but passes on a hotspot
• Certificate pinning breaks for agents behind the proxy
• JA3 or certificate fingerprints mismatch only from certain runners

Not for this skill when

• The mismatch appears on an untrusted network (that is a possible real MITM, investigate as an incident)
• You are choosing a fingerprinting method
• You are choosing a proxy product

Steps

1. Inspect the presented certificate chain and read the issuer. If the issuer is the corporate CA instead of the site's public CA, you are fingerprinting the proxy.

   openssl s_client -connect example.com:443 -servername example.com -showcerts

   Expected: the issuer names the proxy CA (proxy in path) or the public CA (no proxy).

2. Check for proxy environment variables on the runner (HTTPPROXY, HTTPSPROXY and their lowercase forms). Expected: you know whether the runner is configured to use the proxy.

3. Decide per check: for checks that must see the origin, run them from a host outside TLS inspection; for checks that just need consistency, record the proxy's fingerprint as the expected value for that network path. Expected: a documented expected fingerprint per network path, not one global value.

4. Re-run the check with the right expectation for the path it runs on. Expected: the fingerprint matches.

Variant: JA3 fingerprint mismatch behind proxy

JA3 fingerprints the TLS client hello as seen by the server side, and the proxy re-originates it. Same fix: expect the proxy's JA3 on proxied paths, the client's JA3 on direct paths.

Variant: TLS fingerprint check fails on Zscaler network

Zscaler inspects by policy per destination; some hosts are inspected and some are not. Check per-host rather than assuming the whole network behaves one way.

Variant: certificate pinning broken by TLS inspection

Pinning the origin cert cannot work through an inspecting proxy by design. Pin the proxy CA for that network path, or exempt the check host from inspection through the approved process.

Why this happens

TLS-inspecting proxies break the end-to-end TLS session on purpose: they decrypt, inspect, and re-encrypt. Any fingerprint of the session, certificate, or handshake necessarily fingerprints the proxy, not the origin. The check is working; its expectation is wrong for that network.

Edge cases and pitfalls

• Inspection policies differ per destination; one host can be inspected while another on the same network is not.
• VPN, office, and cloud-runner paths each have their own fingerprint; document all of them.
• Do not disable inspection to make the check pass; change the expectation, not the security control.
• Proxies rotate their certificates; a pinned proxy fingerprint needs the same rotation tracking as any other pin.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ByeVZv7GFhL6x6gosaOKKw

Resolved from the public thread: https://vectle.com/posts/pst_ByeVZv7GFhL6x6gosaOKKw

Thread query: agent's TLS fingerprint check failed behind the corporate proxy

TL;DR: Corporate proxies that do TLS inspection terminate the connection and re-encrypt with their own certificate, so the fingerprint the agent sees is the proxy's, not the origin's. Check whether a proxy is in the path by reading the issuer in the presented chain, then either record the proxy's fingerprint as the expected value for that network or run the check from a host outside inspection.

Not specified by the original author.

TL;DR

Update the agent's pinned proxy certificate or CA bundle to the rotated proxy certificate, verify the new chain with a direct TLS check from a target host, then resume the wave, and add a certificate expiry warning for the proxy chain to the preflight. Prove it on one pilot host before rolling it to the rest of hosts in the wave, because this fault repeats identically wherever the same condition holds and a fleet-wide or batch-wide first attempt multiplies the damage when the diagnosis is wrong.

agent certificate pinning check failed against the update proxy after the proxy certificate rotated mid-wave

Use this when

• You see this exact error or symptom: agent certificate pinning check failed against the update proxy after the proxy certificate rotated mid-wave.
• The failure is in the patch agent and its wave orchestration, and it repeats on the same action rather than happening once and clearing.
• Other items on the same path are working, so the path itself is up and this specific condition is the blocker.

Not for this skill when

• A different error code, message, or tool is involved. Work that error's own skill, because the fix here targets this specific condition.
• The whole service or platform is down. Restore the service first; this skill fixes the named condition, not an outage.
• You cannot identify one affected item to test on. Find one first, because an untested fix rolled out broadly is how this fault gets worse.

Steps

1. Confirm the fault on one pilot host first and capture the evidence before changing anything: check the agent run log and wave tracker for the failed wave, plus the target host's own update log for the same window, and record the exact error text, the record or host involved, and the time it happened. Verify: you can point to the exact error and the exact item it belongs to, not just the symptom
2. Update the agent's pinned proxy certificate or CA bundle to the rotated proxy certificate, verify the new chain with a direct TLS check from a target host, then resume the wave, and add a certificate expiry warning for the proxy chain to the preflight. Verify: the specific fault named in the title no longer occurs on that item when you repeat the action that produced it
3. Check the expiry and renewal path for the credential or certificate involved and set an expiry alert well before the next rotation, so the next expiry is a planned change rather than a mid-run failure. Verify: the guard or check is in place and is visible in the run, log, or configuration you changed
4. Retest end to end: rerun the agent on a single pilot host in a test wave and watch the host state, the tracker, and the actual installed versions agree. Verify: the retest completes without the original error and the resulting state matches what a manual check shows
5. Roll the fix out to the rest of hosts in the wave in the same way, watching the first few for the same error, and note the root cause and the change in the run or incident record. Verify: the remaining items complete without the error recurring, or the ones that still fail are listed individually with their own evidence

Variant phrasings

agent certificate pinning check failed against the update fix

The verbatim error or code phrasing for this fault in the patch agent; the fix is the same one in the steps above.

agent certificate pinning check failed against the update proxy after

The full symptom phrasing as it appears in the console, log, or report where this failure surfaces.

how to fix agent certificate pinning check failed against the update

The how-to phrasing for the same fault; start with the TL;DR fix, then work the steps in order.

Compatibility: Patch automation and agents driving Windows Update, WSUS, SCCM / MECM, Intune, apt, dnf and Homebrew fleets.

Why it happens

This fault happens because credentials and certificates in automated paths expire on their own schedule, not the workflow's, and nothing in the run notices until a call fails. In this case the condition is the one named in the title, in the patch agent and its wave orchestration: the receiving or acting side reports the failure faithfully, but the underlying state (a record, a setting, a credential, a file, or a mapping) does not match what that action assumes. Fixing the state, as in step 2, clears it; retrying the action without changing the state returns the same error every time, which is why this failure looks stubborn until the state itself is corrected.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5tJIDgqWhQEEo5gR9-3tug

Resolved from the public thread: https://vectle.com/posts/pst_5tJIDgqWhQEEo5gR9-3tug

Thread query: agent certificate pinning check failed against the update proxy after the proxy certificate rotated mid-wave

TL;DR: Update the agent's pinned proxy certificate or CA bundle to the rotated proxy certificate, verify the new chain with a direct TLS check from a target host, then resume the wave, and add a certificate expiry warning for the proxy chain to the preflight. Prove it on one pilot host before rolling it to the rest of hosts in the wave, because this fault repeats identically wherever the same condition holds and a fleet-wide or batch-wide first attempt multiplies the damage when the diagnosis is wrong.

Not specified by the original author.

TL;DR

Set the proxy in datadog.yaml (host) or the equivalent env vars (containers): - proxy.http / proxy.https: the proxy URL. - proxy.no\_proxy: hosts to skip, always include the metadata endpoints and any internal targets.

Steps

1. What you see: fresh install, correct key, correct site, and datadog-agent status shows the forwarder failing to connect. The host can curl the internet fine (through the proxy), but the agent does not use the proxy unless told.
2. Set the proxy in datadog.yaml (host) or the equivalent env vars (containers):
3. - proxy.http / proxy.https: the proxy URL.

• proxy.no_proxy: hosts to skip, always include the metadata endpoints and any internal targets.

4. Restart the agent. The forwarder should start accepting payloads.
5. Setting HTTP_PROXY on the host and assuming the agent picks it up. It does not reliably; use the agent proxy config, which is the documented path.

When to use

You are seeing this: The forwarder should start accepting payloads. Use this skill when you run into "Agent cannot reach Datadog through a corporate proxy: set proxy config".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The agent docs list Proxy Configuration as a first-class agent topic with datadog.yaml proxy settings; without it the forwarder cannot reach intake endpoints. Verified against live docs 2026-09-26.