SikurdHelp
Open Sikurd

An instance won't connect

Credentials saved but polling fails.

Diagnostic order

  1. Can you log into the 3CX admin console manually with the credentials you gave Sikurd? If no, fix that first.
  2. Is the FQDN exactly right? Spell it without https:// and without a trailing slash.
  3. Is the 3CX reachable from the internet? Sikurd polls from our cloud worker. If the PBX is behind a VPN/firewall blocking our IPs, it can't connect.

Common errors

"Invalid Client ID or Secret"

You're using the OAuth path and the API client isn't right. Try:

  • Recreate the API client in 3CX Admin → Admin → API → Add.
  • Confirm the client has management scope enabled.
  • Paste the new client ID + secret.

"Token verification failed: 401"

3CX accepted the login but rejected the management API call. Usually means the user lacks the System owner role. Promote the user or create a new one with System owner.

"Could not reach instance: ECONNREFUSED" / "EHOSTUNREACH"

Network path issue. Either:

  • DNS for the FQDN isn't resolving from our cloud worker.
  • The PBX is behind a firewall blocking outside access.
  • The PBX is offline / powered down.

Test from your machine: dig <fqdn> and curl -I https://<fqdn>/. If those fail from your machine too, fix the network issue first.

"Token verification failed: 502 Bad Gateway"

The PBX is up but mis-responding. Often a 3CX upgrade mid-flight. Wait 5 minutes and try Reauth again.

"Username/password connect error: ..."

Specific message tells you what's wrong. Common ones:

  • "User not allowed to connect" — the 3CX user account doesn't have web admin permission.
  • "Account locked" — too many failed attempts in 3CX; unlock in the 3CX admin.
  • "2FA required" — Sikurd doesn't support 3CX 2FA on the same account. Create a non-2FA service account just for Sikurd.

Status keeps flipping to Degraded

"Degraded" means polling succeeded but a sub-system failed (Users API, Queues API, etc.). Click into the instance → look for the degradedReason line. Common reasons:

  • SystemStatus failed — the PBX is in a weird state. Restart the 3CX service.
  • Subsystems unavailable: Users, Queues — the API user lacks permission. Promote to System owner.

Force a re-poll

From the instance detail → Quick actions card → Force re-poll. Fires a poll immediately, no wait. Useful right after Reauth.

Still stuck

Email help@sikurd.com with:

  • The instance FQDN.
  • The exact error message from the instance detail card.
  • Whether curl -I https://<fqdn>/ works from your laptop.

We'll diagnose from there.