@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 124 lines 5.67 KB
Raw
1 ---
2 title: Troubleshooting
3 description: Diagnose failed DNS challenges, rejected orders, rate limits, and runtime certificate operations.
4 ---
5
6 Start with the error tag and the affected identifier. Verify your DNS path with
7 Let's Encrypt staging before repeatedly placing production orders. Preserve
8 sanitized error metadata, but keep account keys, certificate keys, EAB HMAC
9 values, and authorization headers out of logs.
10
11 ## Missing DNS solver
12
13 `ACME.DnsSolverNotRegistered` means the descriptor's `type` has no registered
14 factory in the stack's provider context. `ACME.providers()` registers the
15 Cloudflare solver, so include it in the stack's `providers`. For runtime issuance, use
16 `zoneSolver(dns)` with a bound DNS client instead of passing the deploy-time
17 descriptor returned by `ZoneSolver`.
18
19 ## DNS API access fails
20
21 `ACME.DnsSolverError` wraps a failure publishing or cleaning up a challenge.
22 Check the zone ID, credential scope, and whether the DNS name belongs to that
23 zone. An API credential valid for one Cloudflare account is not necessarily
24 valid for another account's zone.
25
26 For runtime `WriteDnsHttp`, the deployment identity must also be allowed to
27 create the scoped token. A failed cleanup is operationally significant even
28 if the CA validated the name; inspect the TXT records and retry cleanup safely.
29
30 ## TXT propagation times out
31
32 `ACME.DnsPropagationTimeout` identifies the challenge name that was not observed
33 within the configured budget. Check authoritative delegation, the zone ID, the
34 exact TXT value, and whether there is an existing CNAME at that name. Public
35 recursive DNS may still have a negative or previous-value cache entry.
36
37 The deploy-time Cloudflare timeout defaults to 90 seconds and includes the
38 60-second post-visibility delay. A timeout shorter than the delay cannot work.
39 Lookup attempts are also bounded; increasing `timeout` alone does not remove
40 that cap. See [DNS validation](/acme/dns-validation#adjust-the-propagation-budget).
41
42 ## The CA rejects a challenge
43
44 `ACME.ChallengeFailed` carries the identifier, CA problem type, and detail.
45 `ACME.OrderInvalid` carries the order URL and reported problems. A successful
46 DNS API write does not prove that every CA validator sees the record.
47
48 For an "incorrect TXT record" failure, inspect stale records and cached values
49 before shortening propagation delays or retrying. Check CAA policy if the CA
50 reports that it is not authorized to issue. Wildcards require DNS-01 support;
51 `ACME.ChallengeUnsupported` reports the challenge types the CA offered instead.
52
53 ## An order times out
54
55 `ACME.OrderTimeout` means polling did not reach a terminal state within the
56 implementation's bounded polling budget. Keep the order URL and status for
57 investigation. The CA may finish processing later; immediately starting another
58 order can consume additional issuance allowance without resolving the original
59 problem.
60
61 ## Rate limits
62
63 The SDK exposes `AcmeRateLimited` and an optional `retryAfter` Effect `Duration`.
64 Honor that hint when scheduling the next attempt. The [runtime Worker example](/acme/runtime#assemble-the-worker)
65 returns HTTP 429 and a `Retry-After` header when the hint is available.
66
67 SDK retries apply to individual protocol requests, not a durable end-to-end
68 certificate job. If you need protocol errors to surface without the default
69 request retries, add `@distilled.cloud/acme` as a direct dependency and provide
70 its retry policy around the operation:
71
72 ```typescript
73 import * as Acme from "@distilled.cloud/acme";
74
75 const issued = yield* issuer.issue({
76 identifiers: ["api.example.com"],
77 solver,
78 }).pipe(Acme.Retry.none);
79 ```
80
81 Disabling retries does not bypass the CA's limits. Keep renewal jobs serialized,
82 reuse valid stored certificates, and avoid an unbounded retry around `issue`.
83
84 ## Staging certificates are untrusted
85
86 A Let's Encrypt staging certificate can be correctly issued and still fail
87 browser trust checks. Use staging to validate your flow, then switch to a
88 production CA in the intended stage. Uploading a staging chain to a public
89 consumer does not make it trusted.
90
91 ## ZeroSSL rejects account registration
92
93 Confirm that `eab.keyId` and `eab.hmacKey` are the matching CA-issued pair. The
94 HMAC value is not your ZeroSSL API key. Keep its base64url encoding intact, load
95 it as a redacted secret, and verify that the account uses `ACME.ZeroSSL` rather
96 than another CA's directory.
97
98 ## A CA works locally but fails in a Worker
99
100 Check connectivity from the deployed host, not only from your laptop. Live tests
101 encountered Let's Encrypt TLS failures from Cloudflare Workers, so the deployed
102 example uses ZeroSSL. For private CAs, `trustedRoot` currently relies on Bun's
103 fetch TLS option and is not a portable Worker trust-store override.
104
105 A Cloudflare runtime solver waits 60 seconds by default. Ensure the request and
106 client remain alive long enough. Use a durable job design for issuance that must
107 continue independently of a disconnected HTTP client.
108
109 ## A deployed certificate has not renewed
110
111 Check that a deployment actually ran against the correct stack and stage with
112 access to the same state. Renewal is evaluated on deployment; it has no
113 background scheduler. Verify that `notAfter` is within `renewBefore`, then check
114 whether the consumer loaded the updated output.
115
116 The resource's read operation uses persisted certificate attributes rather than
117 checking revocation status at the CA. If you revoked a certificate out of band,
118 do not assume the next read will detect it and issue a replacement automatically.
119
120 ## Certificate and private key do not match
121
122 Use the certificate's `chain` and `privateKey` from the same issuance result.
123 The account private key signs ACME requests and cannot serve as the TLS key.
124 After renewal, update both values together and reload the TLS consumer.