Troubleshooting

Common issues with the splashify CLI and how to fix them. Start with splashify doctor — it checks most of these automatically.

Issues specific to the OpenClaw skill (the assistant not seeing the skill, installing the bundle) are covered in OpenClaw → Troubleshooting. This page covers the CLI itself.

`splashify doctor` checklist

splashify doctor

Check	If it fails
config	Run `splashify connect` to save your backend URL and token.
access token	The token is invalid, revoked, or expired — create a new one.
openclaw	Only needed for the skill — install with `npm install -g openclaw@latest`.
splashify skill	Only needed for the skill — run `splashify link openclaw`.

For CLI-only use, only config and access token must pass.

Common problems

"not connected — run `splashify connect` first"

The CLI has no saved configuration. Run splashify connect and paste an oc_live_ token.

Token validation failed / HTTP 401

The token is invalid, revoked, or expired. Create a fresh token from Settings → Developer → Access Tokens (or splashify token create) and run splashify connect again.

"Access tokens are not enabled on this server yet"

The Splashify Pro backend is still completing a rollout (a database migration is pending). Wait a short while and retry, or contact support — no action is needed on your side.

A message or template send fails

Free-form text messages only work inside the 24-hour customer service window. Outside it, use a template (splashify message template …).
Template messages require an approved template — run splashify templates to see valid names and languages.
Include the country code in phone numbers, e.g. +919876543210.

Rate limited (HTTP 429)

Access tokens share your plan's API rate limit. Slow down requests, or upgrade your plan for a higher limit.

"Account is not active"

The Splashify Pro account is suspended or inactive. Contact support — access tokens are disabled while an account is not active.

"Your Splashify Pro account does not have a WhatsApp Business Account connected yet"

The CLI calls /api/v1/app/developer/cli-eligibility during splashify connect to check that the account has a connected WABA. Two things to verify:

You are signed in under the correct account. If the WABA is on a parent account but the token was created under a sub-account / team-member login, the gate will refuse — switch to the WABA-owning account and create a new token.
You really do have a connected WABA. Confirm by visiting https://app.splashifypro.com → WhatsApp → Connect Number and finishing Meta Embedded Signup. The status should show your phone number listed.

If you are certain the account has a WABA but the gate is misreporting (this can happen during a backend rollout window), bypass it with:

SPLASHIFY_SKIP_ELIGIBILITY=1 splashify connect

The env-var only skips the WABA check — token validation still runs, so an invalid token still fails. Drop the env-var once the backend deploy completes.

"no_waba" while `splashify waba` shows a real WABA

Same root cause as above — the eligibility query is misreporting. Use SPLASHIFY_SKIP_ELIGIBILITY=1 for the one-time connect, then run any other command normally (only connect is gated; everything else relies on the backend's per-endpoint WABA checks).

"your trial has ended and there is no active paid plan"

The eligibility gate at splashify connect requires an active subscription — either an unexpired trial or an active paid plan. When both have lapsed the CLI refuses with this message and a link to the subscriptions page.

Fix it by subscribing at app.splashifypro.com/settings/subscriptions, then re-run splashify connect. Verify the plan is active with:

splashify subscription | jq '.eligibility'

"this feature requires a higher plan"

A backend endpoint refused a CLI command because the account's plan is below the tier needed for that feature. The CLI prints the current plan, the required plan, the feature ID, and a direct upgrade URL — open the URL to upgrade, then retry the command.

`splashify waba` returns `"needs_sync": true`

The signup data is in place but Meta details haven't been fetched yet. Run:

splashify waba sync
splashify waba          # full details now populated

Still stuck?

Re-run splashify doctor and read each line.
Re-run the failing command with the exact arguments to see the error: … message.
Contact Splashify Pro support with the output of splashify doctor.