Troubleshooting

Map any failure back to a code, then a fix — every command speaks JSON when you ask it to.

Every command takes --output json, and on failure it returns the WordPress REST error envelope so you can branch on code instead of parsing prose. Most first-run failures are authentication or capability problems — if you are just getting set up, start at Authentication and come back here to translate whatever you hit.

Error codes

Code	HTTP	Meaning	Fix
`rest_cannot_view`	401	Missing or bad application password	Re-create the password and quote it (spaces matter)
`rest_forbidden`	403	Authenticated, but the user lacks the capability	Grant the required nwp_* capability to the user
`nwp_feature_disabled`	403	Feature is gated off on your license tier	Upgrade the tier (Surf / Pipeline) or enable the feature
`nwp_*_not_found`	404	The addressed member, tier, card, or redemption does not exist	Check the ID; confirm the resource lives on this site
`nwp_invalid_*`	400	A field failed validation	Read the message — it names the offending field
`nwp_network_error`	—	DNS, TLS, or offline — the request never reached WordPress	Fix WORDPRESS_SITE_URL or connectivity (see below)
`nwp_http_error`	5xx	WordPress reached but errored server-side	Check the WP error log; retry transient 5xx

CLI exit codes

The CLI maps every outcome to a stable exit code so scripts can react without reading the body:

Exit	Meaning
0	Success
1	Crash, usage error, or transport failure
2	Not found (404)
3	Structured domain failure (403 / validation / feature-disabled)
4	Authentication failure (401)

Machine-readable error shape

WordPress REST errors come back in the standard envelope — branch on code and read data.status for the HTTP status:

json

{
  "code": "rest_forbidden",
  "message": "You do not have permission to manage members.",
  "data": { "status": 403 }
}

NextWave's own domain failures use the success envelope with a nwp_* code:

json

{ "success": false, "code": "nwp_member_not_found", "message": "Member not found." }

Driving NextWave from an agent? MCP failures come back as isError: true with the same code embedded in the text payload — so your tool-use loop can branch on it exactly like the CLI does.

Common first-run failures

401 on every call → re-create the application password and quote it in your shell — WordPress prints it with spaces (xxxx xxxx xxxx xxxx) and an unquoted value drops them.
403 rest_forbidden → the user is authenticated but missing the capability for that operation. Grant the matching nwp_* capability and retry.
Network error → WORDPRESS_SITE_URL is wrong or unreachable (DNS / TLS / offline). Pass --insecure only for a local self-signed certificate — never against production.
Everything 404s → set WORDPRESS_SITE_URL to the bare site root (e.g. https://club.example.com). The CLI appends /wp-json/nwp/v1 itself — don't include the REST path.
Approve returns 403 → approving redemptions needs nwp_approve_redemptions specifically. A user who can record redemptions still can't approve them.

Run the doctor first

Before debugging anything else, let NextWave check the site URL, credentials, and REST reachability in one shot:

$ nwp doctor