Joiner

Appearance

Troubleshooting ​

Error codes and failure modes you may hit while building an activity, indexed by the literal string you're looking at. Each entry says what it means, what the user experiences, and what your activity should do.

Bot-access errors ​

Poe-backed model calls require the current user to have a usable Poe account. When they don't, you'll encounter one of the reason codes below — as access.reason from Poe.getPoeBotAccess() / Poe.requestPoeBotAccess().

The fix is the same for all of them — preflight with Poe.requestPoeBotAccess() so the platform prompts the user to repair their account, instead of letting the call fail inside your action:

javascript
async function askAi(model, prompt) {
  const access = await Poe.requestPoeBotAccess();
  if (!access.canUse) return null; // user declined — keep the feature visible, disabled

  // The model round runs in an action (see backend-api.md).
  const { text } = await Poe.store.action.askModel({ model, prompt });
  return text;
}
  • Means: the user has no Poe account linked to their Joiner account.
  • User sees (with the preflight): the platform's "Link your Poe account" modal — they can sign in with Poe or paste an API key without leaving your activity.
  • Your activity: call requestPoeBotAccess() before the bot call; on { canUse: false }, keep the AI feature visible but inert. Don't hide it — the user may link later and retry.
  • Means: a Poe account was linked, but its key expired or was revoked.
  • User sees (with the preflight): the platform's "Reconnect your Poe account" modal.
  • Your activity: same preflight pattern; nothing extra to handle.

poe_pay_with_points_required ​

  • Means: the linked Poe account hasn't enabled paying for bot calls with Poe points.
  • User sees (with the preflight): the platform's "Enable Poe points" modal.
  • Your activity: same preflight pattern.

poe_bot_backend_unavailable ​

  • Means: Poe-backed bots aren't available in this environment at all (nothing the user can fix).
  • User sees (with the preflight): an informational "AI is unavailable" modal.
  • Your activity: same preflight pattern; consider degrading the AI feature with an inline "unavailable here" hint if getPoeBotAccess() reports this reason at load time.

No API key configured for user ​

The raw server-side message behind poe_link_required, thrown by the model round inside your action when it ran without a successful preflight. There is no typed client error to catch — the call is server-side, so what you get is a rejected action. Adopt the preflight pattern above so the user is prompted to link before the round starts.

"This API doesn't exist" / TypeScript can't find a method the docs describe ​

These docs describe the latest published SDK. If TypeScript (or a runtime undefined is not a function) says a documented method doesn't exist, your app's poe-tiles-sdk pin predates the API — see Upgrading an existing app's SDK. Newer API sections in the client API reference carry an Added <date> note you can compare against your pin's publishedAt date.

poe-tiles doctor failures on an older scaffold ​

If doctor complains about a missing publish-to-poe-tiles script, your vite.config.ts imports poeApp and fails to build, or publishes 404 — your app predates the platform rename. Work through Migrating a pre-rename app.