Chapter 13

When it breaks

Things go wrong. It is not a sign you are bad at this: every message below was hit by someone who then wrote down what fixed it. Find your symptom, read the cause, apply the fix.

Updated 5 Nov 2026Pega 24 – 26

Words you will meet

Errors
FAQ

On this page4

01First, stay calm
02Find your symptom
03Node 26: sign-in says fetch failed
04If yours is not listed

A mindset

Errors are clues.

An error message is the tool telling you, precisely, what it did not like. Read it slowly and read the first one, not the last: a dozen errors are often one mistake repeated. Copy the exact wording into the search box below.

Find your symptom.

Each entry says where the answer came from: this project's own notes, a message printed by the builder itself, or a common cause rather than a documented one.

TroubleshooterTry it: type a word from your error

What does the screen say?

20 matches

A known one

Node 26: sign-in says fetch failed.

Node 24 or newer is fine for this guide. On Node 26, signing in can stop with Token endpoint error: TypeError: fetch failed. Your credentials and your network are not the problem.

Why it happens. The sign-in libraries bring their own copy of a networking package called undici, and that copy is older (version 6 or 7) than the one built into Node 26 (version 8). Mixing the two breaks fetch with UND_ERR_INVALID_ARG: invalid onError method.

The fix

Needs Node 22.19 or newer. Do these in order.

Add two entries to package.json. The first puts the new version in. The second forces the older copies nested inside @pega/auth and @pega/custom-dx-components to use it too. Without the second, the old copies stay and the error continues.

package.json (create the overrides block if it is missing)

{  "devDependencies": {    "undici": "^8.12.3"  },  "overrides": {    "undici": "$undici"  }}

Install. Run npm install.
Check there is one copy. Run npm ls undici. It should list undici@8.x everywhere.
Sign in again. Run npm run authenticate. It should print Authenticated successfully !!.

Source: reported by the guide’s author from a real Node 26 sign-in failure. It has not been re-tested on every setup, so check npm ls undici after you apply it.

When you are stuck

If yours is not listed.

Re-run the failing command alone. Is it the same error every time?
Check what changed. The last thing you edited is usually the cause. Git can show you: git status and git diff.
Run npm run verify. It narrows the problem to one of four stages.
Ask with the facts. The exact command, the full message, your Node version, and what you already tried.

Your turn

Questions and comments

Stuck on something, or have a thought? Write it here. To talk about one part, use the Comment button under that section's heading.