HockeyStick Knowledge Base Knowledge Base Open Command Centre

Slack agent

Troubleshooting playbook

Work through link failures, no credit, workspace conflicts, a silent agent and stale configuration, in order.

Troubleshooting playbook

Start from the exact message the customer saw. Most map to one cause. Ask for a screenshot and the time, then work down the matching section.

"HockeyStick isn't turned on for you yet"

The licence or the organisation switch is missing.

  1. In the client's HSAI Agent tab, check step 1 has a current seat agreement and the person has a licence.
  2. Ask the customer administrator whether Slack for your organisation shows On.
  3. Check the person is a customer user in this organisation. Staff accounts are never admitted.

"Your organisation has no agent credit available right now"

  1. Step 2: agent terms enabled, in window, with a margin.
  2. Step 3: credit applied for a current period (approved but not applied adds nothing).
  3. Step 4: the person has an allocation, and organisation and person limits are not 0 or reached.
  4. Remember the hold: a balance below one call's hold is refused. See Pricing, credit and limits.
  5. Check for an unreviewed pricing exception blocking the account.
SymptomCheck
"Account linking is not available yet"The runtime is not admitted. Run the preflight in the API container.
"Account linking is available only to full members of this workspace"The person is a Slack guest.
"You're not signed in to HockeyStick"They must be signed in to the portal in the same browser, then reuse the link from Slack.
"Unable to connect. Please reconnect or contact your administrator."Usually an expired link (ten minutes) or a stale confirmation. Send a new message for a fresh button.
"Your HockeyStick connection needs to be renewed"Link revoked, expired, or the workspace was disconnected or reconnected. Relink from App Home.

Workspace bound to another organisation

The portal refuses the connection ("Workspace connection is not authorised or is no longer current."), or Slack says the workspace is connected to another organisation. The other organisation's administrator must disconnect it. Confirm with the customer which organisation should own it before involving anyone else.

Install or connection errors

Branded error pages show a Support reference. Search the API logs for slack_install_failed with that reference to see the category (session, cancelled, configuration, provider, storage, service, request). Session errors mean they took longer than ten minutes or switched browsers.

Agent not replying

  1. Check API health: the Slack detail should show receiverMounted true and durableAgent true.
  2. Confirm the person is messaging in Messages, not a channel. Channel mentions only get a private nudge.
  3. Check Slack's Event Subscriptions shows the request URL verified for the right environment.
  4. Look for slack_event log lines for that user and time. None means Slack is not reaching the API.
  5. A turn that failed before posting is retried, then the person gets "I couldn't finish that request."

Stale runtime configuration

  • Settings are read at API start. After a change, sync with restart_services=true.
  • Run node dist/scripts/slack-runtime-preflight.js in the container and read blockers and warnings. legacy_catalogue_tenant_terms_not_current means an old catalogue price expired; enable agent terms in step 2.
  • Writes enabled but the person still cannot save: their link was made under read-only. Ask them to unlink and reconnect.
  • App Home text tells you the mode the person sees: read only, changes without paid generation, or full.