Troubleshooting
Get the smallest failing case you can, and save its output before you change anything — the output is usually all you get.
Then check in this order: package versions, runtime, identity, then the record. That order is not arbitrary; each layer depends on the one before it, and most “identity” problems turn out to be version problems.
Never fix a failure by editing events, and never paste a secret into a log to see what’s in it.
Check where the packages are coming from, the version ranges in the starter, and your Node.js and pnpm versions.
A missing package or an unresolvable tarball is a release problem, not something to work around. Go back to Install and verify the release.
Check that you have Compose v2, that the pinned PostgreSQL image is the one running, that the container is reachable, and that the test can create and drop its own schema.
Do not swap in an in-memory database to make the test pass. It passes without testing the thing you care about.
Check the proxy and the trusted CA before you touch application code. Corporate TLS interception accounts for a good share of “it works on my machine”.
Both the local OIDC issuer and the package source have to be reachable. Keep trust setup explicit and on your machine.
Signing and release promotion are not part of what runs today.
If an older instruction asks you to do either, stop and use the second-directory exercise instead. Don’t work around a step that doesn’t exist yet.
Check that the origin someone authenticated through routes to siam, then check
which principals that account actually has.
Similar-looking text under a different provider is not a match, and it is supposed to fail. If you are surprised by a denial here, compare the provider IDs first.
Read the WorkflowTestError code before anything else. It’s stable and it
usually names the problem outright.
The most common one by a distance: a binding with no test double registered.
Register it before start() and re-run.
Keep the redacted error output — it’s safe to share — and check that PostgreSQL cleaned up after itself before you start deleting things by hand. See Testing Workflows.
The optional live exercise has a five-minute preflight. If the endpoint or the
credentials aren’t there, note it as live-role-engine: preview-only and
continue on prepared data.
This does not affect the status of anything else. Nothing that was working stops working.