Applies to: Octopus Prime channel plugin 1.1.0 · OpenClaw ≥ 2026.9.8 · Last verified: 2026-10-10

Full index: /ai/llms.txt · Markdown: append .md to any /ai/ URL

# Error catalog

Exact texts are copied verbatim (placeholders in angle brackets or braces). Search this page for a distinctive fragment of the message you see. Machine-readable version: /ai/errors.json. Symptom-first guidance: /ai/troubleshooting.

Service errors have no numeric codes: every HTTP error body is `{"detail": "<text>"}` (validation errors with status 422 may be a list of field errors). Plugin errors appear in the output of `openclaw channels add`, in the Gateway log (`openclaw channels logs --channel octopus-prime`, `openclaw logs --follow`; lines start with `octopus-prime`) or in the `error` field of `openclaw channels status --probe --channel octopus-prime --json`.

## Plugin setup errors

Printed by `openclaw channels add --channel octopus-prime …`. When setup fails, nothing is written to the OpenClaw config.

| Exact text | Where | Cause | Fix | Verify |
|---|---|---|---|---|
| `Octopus Prime setup code is required` | Output of openclaw channels add --channel octopus-prime | The command ran without --setup-code. | Create a code in the web app (OpenClaw Agents → Connect OpenClaw, or New setup code) and run openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code <code> | The command finishes without error and the connector leaves SETUP REQUIRED. |
| `Octopus Prime AI bootstrap failed (<HTTP status>): <server body>` | Output of openclaw channels add; <server body> is the service's JSON, for example {"detail":"Invalid or used setup code"} | The setup-code exchange (POST /api/connector/bootstrap) was refused. Read the detail: 404 Invalid or used setup code, 410 Setup code expired, 404 Connector not found, 404 Connector revoked, 409 Organization is archived, 426 Unsupported OpenClaw plugin API <v>. Supported: ['2026.9.7']. | Fix by detail (see the service errors for the bootstrap endpoint): new code for used/expired codes; Connect OpenClaw again for a missing or revoked connector; an Owner restores an archived organization; install the plugin package Octopus Prime provides for 426. | Rerun succeeds; the connector moves from SETUP REQUIRED to CONNECTING. |
| `Octopus Prime AI bootstrap returned an incomplete connector credential` | Output of openclaw channels add | The exchange answered successfully but without the credential or identifiers (service or proxy problem). Nothing was written. | Retry with a new setup code after a few minutes; check that no proxy rewrites HTTPS responses; if it repeats, contact support with openclaw triage --non-interactive output. | Rerun succeeds. |
| `Octopus Prime requires a valid authenticated connector identity` | Output of openclaw channels add | The exchange returned an invalid connector id. | Same as the incomplete-credential case: retry with a new code; contact support if it repeats. | Rerun succeeds. |
| `Octopus Prime requires a valid authenticated organization identity` | Output of openclaw channels add | The exchange returned an invalid organization id. | Retry with a new code; contact support if it repeats. | Rerun succeeds. |
| `Octopus Prime AI bootstrap backend identity does not match the requested canonical backend` | Output of openclaw channels add | The backend that answered is not the one named in --backend-url (wrong URL, or a redirect or proxy in between). | Use exactly --backend-url 'https://api.octopusprimeai.com' and make sure nothing redirects it. | Rerun succeeds. |
| `Invalid ingress origin URL` | Output of openclaw channels add | --backend-url is not a valid URL. | Use exactly 'https://api.octopusprimeai.com'. | Rerun succeeds. |
| `Ingress origin requires a secure HTTPS URL without credentials, query or fragment` | Output of openclaw channels add | --backend-url is not https:// or contains user:password@, ?query or #fragment. | Use exactly 'https://api.octopusprimeai.com'. | Rerun succeeds. |
| `Octopus Prime supports the default connector account only` | Output of openclaw channels add | --account was given with a value other than the default account. | Remove --account. One Gateway (OpenClaw profile) connects to one organization; use a separate profile or Gateway for another organization. | Rerun succeeds. |
| `Octopus Prime setup must complete authenticated connector exchange before configuration is written` | Output of openclaw channels add | Setup was asked to write config without a successful code exchange (for example only --connector-token, --connector-id or --org-id were passed). | Run setup with --setup-code: openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code <code> | Rerun succeeds; channels.octopus-prime is written. |
| `DNS, TLS or timeout error during setup (text comes from the operating system or runtime)` | Output of openclaw channels add | The Gateway host cannot reach https://api.octopusprimeai.com (no outbound HTTPS, DNS, firewall or proxy problem). | Fix outbound HTTPS from the Gateway host, then rerun setup (with a new code if 15 minutes have passed). | curl -sS https://api.octopusprimeai.com/api/health/live prints {"status":"live"}. |

## Plugin runtime errors

Gateway log lines, rejection reasons and `channels status` errors while the plugin runs.

| Exact text | Where | Cause | Fix | Verify |
|---|---|---|---|---|
| `octopus-prime connector socket closed (code <N>); reconnecting in <n> seconds` | Gateway log (warning); openclaw channels logs --channel octopus-prime | The connection to the service closed with close code N; n is the backoff (2, 4, 8, then 15 s). | Look up N under Connection close codes (4401, 4403, 4426, 1002, 1001, 1011, 1012). Occasional 1006 or 1012 lines are normal; a repeating code is not. | The line stops repeating and the connector shows READY. |
| `octopus-prime connector socket was silent for 50 seconds; reconnecting in <n> seconds` | Gateway log | No frame arrived for 50 s (network drop, sleeping host, or a proxy that kills idle or long-lived WebSockets). | Usually recovers by itself. If it repeats, check outbound WSS stability, proxy idle timeouts and host sleep settings. | No new lines; connector READY. |
| `octopus-prime connector socket could not be created; reconnecting in <n> seconds` | Gateway log | The WebSocket could not be opened (bad backendUrl or no network). | Check channels.octopus-prime.backendUrl is https://api.octopusprimeai.com and outbound WSS is allowed. | Connector READY. |
| `<issue>. Run Octopus Prime setup, then restart this channel account.` | error field of openclaw channels status (account inspect); issue is one of: Octopus Prime requires a resolved connector credential · Octopus Prime requires a canonical HTTPS backend URL · Octopus Prime requires a valid connector identity pin · Octopus Prime requires a valid organization identity pin | channels.octopus-prime is missing or invalid: no connectorToken (or a SecretRef that does not resolve), a non-canonical backendUrl, or invalid connectorId/orgId. | Create a new setup code and rerun setup. For a SecretRef credential, fix the secret source and run openclaw secrets reload. | tokenStatus: "available" and statusState: "ready" in openclaw channels status --probe --channel octopus-prime --json. |
| `Connector pin changed; restart the Octopus Prime channel account to activate the new identity generation` | openclaw channels status (statusState restart-required) | connectorId or orgId changed while the account was running (after setup with a code for a different connector). | openclaw gateway restart (add --safe to wait for active work). | statusState: "ready"; connector READY. |
| `Authenticated connector does not match the configured connector identity pin` | openclaw channels status (statusState error; transport stopped) | The credential belongs to a different connector than connectorId, usually because config from two setups was mixed or copied. | Create a new setup code for the intended connector and rerun setup; do not hand-edit connectorId, orgId or connectorToken. | statusState: "ready". |
| `Authenticated connector changed within an active ingress generation` | Gateway log or channels status | Config identity changed under a running connection. | Restart after config changes: openclaw gateway restart. | Connector READY. |
| `Current configuration does not match the authenticated ingress origin` | Gateway log or channels status | backendUrl or ids were edited while the connection was running. | openclaw gateway restart; prefer rerunning setup over hand edits. | Connector READY. |
| `Current configuration no longer matches the authenticated outbound origin` | Gateway log or channels status | Config was edited while replies were being sent. | openclaw gateway restart. | Connector READY. |
| `Connector outbound readiness generation is no longer current` | Gateway log or channels status | The connection restarted while a reply was pending. | Usually transient; if it persists, openclaw gateway restart. | Replies arrive. |
| `Backend did not return the exact negotiated connector contract` | Gateway log (octopus-prime inbound error: …); the plugin closes the connection with 1002 protocol-error | Protocol mismatch between plugin and service, or a proxy altering WebSocket traffic. | Install the plugin package Octopus Prime currently provides; bypass WebSocket-inspecting proxies; contact support if it persists. | Reconnect succeeds; connector READY. |
| `Protocol welcome is not an object` | Gateway log (octopus-prime inbound error: …); closes 1002 | Unexpected frame from the service or a proxy. | As above. | Reconnect succeeds. |
| `Backend sent application data before protocol negotiation completed` | Gateway log (octopus-prime inbound error: …); closes 1002 | Protocol order violated (version mismatch or proxy). | As above. | Reconnect succeeds. |
| `Connector frame is not an object` | Gateway log (octopus-prime inbound error: …); closes 1002 (invalid JSON closes 1002 invalid-json) | Malformed frame. | As above. | Reconnect succeeds. |
| `Agent is not currently announced by this connector` | Sent by the plugin as a rejection reason; the message's chip becomes FAILED (last_error connector_rejected) | Octopus Prime targeted an agent id that this Gateway no longer has (agent removed or renamed id in OpenClaw). | Restore the agent in OpenClaw (openclaw agents list) or message an agent that exists. New messages deliver once the agent is announced again. | A new message reaches RESPONDED. |
| `Inbound message is missing stable event, channel, agent, sender, or body facts` | Plugin rejection reason; chip FAILED | Malformed delivery from the service. | Contact support with the time and conversation; include openclaw triage --non-interactive output. | — |
| `Inbound thread id is invalid` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
| `Inbound sender name is invalid` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
| `Inbound timestamp is invalid` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
| `Inbound frame is not an object` | Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
| `Octopus target agent is not currently configured` | Dispatch error in the Gateway log | The delivery names an agent id that is not in the Gateway's agent list. | Add or restore the agent in OpenClaw (openclaw agents list), or use another agent in Octopus Prime. | A new message reaches RESPONDED. |
| `Octopus connector account is disabled` | Dispatch error | channels.octopus-prime.enabled is false. | openclaw plugins enable octopus-prime and/or set channels.octopus-prime.enabled back to true. | Connector READY. |
| `Octopus connector account is unavailable` | Dispatch error | A non-default OpenClaw account was addressed. | Use only the default account; remove any accounts config for octopus-prime. | Connector READY. |
| `OpenClaw did not dispatch admitted Octopus event <event_id>` | Gateway log | OpenClaw core declined to run the agent turn (agent configuration, model or provider error). | Read openclaw logs --follow around that time; fix the agent or model configuration; ask the person to send the message again. | Chip goes WORKING then RESPONDED. |
| `octopus-prime Working status could not be sent` | Gateway log | The connection dropped during a turn. | Transient; check connectivity if frequent. | — |
| `octopus-prime outbound delivery failed: <error>` | Gateway log | Sending a reply failed; OpenClaw core retries it (on 2026.9.8 up to 5 attempts, 5 s to 10 min apart). | Read the inner <error> (entries below). | The reply appears; chip RESPONDED. |
| `Timed out waiting for backend send receipt` | Inner error of octopus-prime outbound delivery failed | No receipt within 20 s. Includes the case where the agent was removed from the conversation or the conversation was archived (the service ignores the reply). | Check the agent is still in the conversation and the conversation is active; otherwise check the connection. | Next reply appears. |
| `Timed out waiting for backend status receipt` | Inner error | Same as the send-receipt timeout. | Same as above. | Next reply appears. |
| `Connector is not ready with a current authenticated and explicitly pinned outbound origin` | Inner error | A reply was attempted while the connection was down for more than 30 s. | Restore connectivity; OpenClaw core retries. | Reply appears after reconnect. |
| `Connector socket closed before backend receipt` | Inner error | The connection dropped while sending. | Transient; OpenClaw core retries. | Reply appears. |
| `Connector transport stopped before backend receipt` | Inner error | The channel stopped (restart, disable) while sending. | Transient; OpenClaw core retries. | Reply appears. |
| `Backend rejected outbound intent: <reason>` | Inner error, permanent (not retried) | reason source_expired: the triggering message is older than the 30-day window; channel_unavailable: the conversation is no longer available to the agent; identity_conflict: the same reply id was reused with different text. | Nothing to retry for source_expired; for channel_unavailable re-add the agent or use an active conversation; identity_conflict indicates a bug: contact support. | — |
| `Backend outbound receipt omitted message identity` | Inner error | Unexpected service response. | Contact support. | — |
| `Backend returned an invalid outbound status receipt` | Inner error | Unexpected service response. | Contact support. | — |
| `Backend did not accept outbound intent` | Inner error | Unexpected service response. | Contact support. | — |
| `The Octopus Prime reply connector changed during this turn; delivery was not started.` | Gateway log (not retried) | The channel account restarted or was re-pinned during the agent's turn. | Ask the agent again once the connector is READY. | Reply appears. |
| `Octopus Prime outbound currently supports one durable text part only` | Send error | The agent tried to send media or a multi-part message. | Agents reply with plain text only; no files or media. | Text replies arrive. |
| `Durable outbound, parent event, and channel identities are required` | Send error | The agent tried to send something that is not a reply to an Octopus Prime message (for example a proactive send). | Agents can only answer messages they received from Octopus Prime. | — |
| `Octopus Prime outbound requires the durable message adapter` | Send error | A non-durable send path was used. | Only replies to received messages are supported. | — |
| `Octopus Prime replies require durable core-managed delivery` | Send error | A non-durable send path was used. | Only replies to received messages are supported. | — |
| `Build 10 pilot outbound supports only the octopus-prime default account` | Send error (permanent) | A send targeted a non-default account. | Use only the default account. | — |
| `Build 10 pilot outbound requires a channel target` | Send error (permanent) | A send targeted something other than an Octopus Prime conversation. | Only reply within the conversation the message came from. | — |
| `Octopus Prime host runtime is not bound` | Gateway startup log | Startup race inside the Gateway. | openclaw gateway restart; if it persists reinstall the plugin package with --force. | Connector READY. |
| `Octopus Prime host runtime is unavailable` | Gateway startup log | Startup race or failed plugin load. | openclaw gateway restart; check openclaw plugins inspect octopus-prime --runtime --json. | Connector READY. |
| `Octopus Prime connector account is already running` | Gateway startup log | Double start of the channel account. | openclaw gateway restart. | Connector READY. |
| `Octopus Prime transport is already started` | Gateway startup log | Double start of the transport. | openclaw gateway restart. | Connector READY. |
| `prepared payload capability mismatch (thread)` | Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0 (openclaw plugins install <plugin package> --force). | Replies arrive. |
| `The reply channel changed or cannot preserve its sender` | Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0. | Replies arrive. |
| `Delivery platform claim was lost` | Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0. | Replies arrive. |
| `Plugin config repair could not be inspected` | Output of openclaw plugins install --force or openclaw plugins update on OpenClaw 2026.9.8 (reported in the plugin's own notes; not OpenClaw documentation wording) | Replacing a plugin build that lacks a Doctor contract. | Install plugin 1.1.0, which ships the Doctor contract. | The install completes; openclaw plugins inspect octopus-prime --runtime --json shows loaded. |

## Connection close codes

Close codes of the plugin's WebSocket to `wss://api.octopusprimeai.com/api/connector/ws`, shown as `octopus-prime connector socket closed (code <N>); reconnecting in <n> seconds`. The plugin always reconnects with backoff 2, 4, 8, then every 15 s.

| Code | Where | Cause | Fix | Verify |
|---|---|---|---|---|
| `4401` | Close code in octopus-prime connector socket closed (code 4401) | The connection carried no credential. | Rerun setup with a new code (channels.octopus-prime.connectorToken is missing). | Connector READY. |
| `4403` | Close code in octopus-prime connector socket closed (code 4403) | Credential unknown or revoked, organization archived, or replaced by a newer connection using the same credential (two Gateways or processes with the same config). | Revoked/rotated: Connect OpenClaw (or New setup code) and rerun setup. Duplicate: stop the second Gateway/profile using the same config, or give it its own connector. Archived organization: an Owner restores it. | No repeating 4403; connector READY. |
| `4426` | Close code; connector chip INCOMPATIBLE | Protocol token not accepted, or no protocol negotiation within 5 s. | Install the plugin package Octopus Prime currently provides (plugin 1.1.0 sends 2026.9.7); check that nothing delays the connection start. | Connector READY. |
| `1002` | Close code | Malformed frame, or the agent roster was rejected (more than 1000 agents, id longer than 128 characters, duplicate ids, name longer than 256, description longer than 4096). | Fix agent ids, names or descriptions in OpenClaw; update the plugin if frames are malformed. | Connector READY; agents listed. |
| `1001` | Close code | No frame for 75 s (idle connection). | Check proxies or firewalls that cut idle or long-lived connections; heartbeats run every 25 s. | No repeating 1001. |
| `1011` | Close code | Service-side error. | Transient; the plugin reconnects. Contact support if it repeats. | Connector READY. |
| `1012` | Close code | The Octopus Prime service restarted. | Nothing; the plugin reconnects automatically. | Connector READY. |
| `1006` | Close code reported locally when the connection dropped without a close frame | Network drop. | Nothing if occasional; the plugin reconnects. | Connector READY. |

## Delivery failure reasons

Reason values behind a `FAILED` (or expired/cancelled) delivery chip.

| Reason | Where | Cause | Fix | Verify |
|---|---|---|---|---|
| `ack_timeout` | Chip FAILED | The plugin did not acknowledge within 20 s on 5 offers (Gateway reachable but not processing, plugin errors). | Check openclaw channels logs --channel octopus-prime and openclaw logs --follow; fix the plugin or Gateway; send the message again. | A new message reaches RESPONDED. |
| `reply_timeout` | Chip FAILED after WORKING or RECEIVED | No progress for 10 minutes (no reply and no Working signal), or the Gateway was down past that limit. | Check the agent's model/provider and tools in openclaw logs --follow. A late reply is still saved and shown. | Next message reaches RESPONDED. |
| `route_unavailable` | Chip FAILED | The agent is inactive, no longer announced by its Gateway, no longer in the conversation, or the conversation is archived. | Restore the agent in OpenClaw or in the conversation; use an active conversation. | Next message reaches RESPONDED. |
| `route_identity_changed` | Chip FAILED | The agent's OpenClaw id changed after the message was accepted. | Keep OpenClaw agent ids stable; message the agent again. | Next message reaches RESPONDED. |
| `stable_identity_missing` | Chip FAILED | The sender or the agent's OpenClaw id was missing. | Send again; contact support if it repeats. | — |
| `sender_access_revoked` | Chip FAILED | The sender was deleted, deactivated or is no longer a participant. | Nothing; the message is not delivered on purpose. | — |
| `source_sender_mismatch` | Chip FAILED | The stored sender no longer matches the message. | Contact support if it repeats. | — |
| `source_retention_expired` | Delivery state expired | The message passed the 30-day window before the Gateway came back. | Send a new message. | — |
| `message_removed` | Delivery state cancelled | The source message was removed. | Nothing. | — |
| `sender_account_revoked` | Delivery state cancelled | The sender deleted their account; their queued agent deliveries are cancelled. | Nothing. | — |
| `connector_rejected` | last_error of a FAILED delivery | The plugin rejected the delivery (for example Agent is not currently announced by this connector). | See the plugin rejection reason in openclaw channels logs --channel octopus-prime. | Next message reaches RESPONDED. |

## Service errors (HTTP detail)

`detail` texts returned by the Octopus Prime service, grouped by area.

### Setup-code exchange (POST /api/connector/bootstrap)

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 404 | `Invalid or used setup code` | setup-code exchange | The code was mistyped, already used, or replaced by a newer code. | Web app: New setup code; rerun setup within 15 minutes. | Setup succeeds. |
| 410 | `Setup code expired` | setup-code exchange | More than 15 minutes passed. | New setup code; rerun setup. | Setup succeeds. |
| 404 | `Connector not found` | setup-code exchange | The connector no longer exists. | Connect OpenClaw again and use its code. | Setup succeeds. |
| 404 | `Connector revoked` | setup-code exchange | The connector was revoked. | Connect OpenClaw (new connector) and use its code. | Setup succeeds. |
| 426 | `Unsupported OpenClaw plugin API <v>. Supported: ['2026.9.7']` | setup-code exchange (checked before the code is used up) | The plugin sends a protocol token the service does not accept (an unsupported plugin build). <v> is the plugin's token, not your OpenClaw version. | Install the plugin package Octopus Prime currently provides (1.1.0 sends 2026.9.7); the same code still works if not expired. | Setup succeeds. |

### Organization

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | `Organization is archived` | any organization action, including setup | The organization was archived. | An Owner restores the organization. | Actions work again. |
| 403 | `Only an owner can access an archived organization` | opening an archived organization | Archived organizations are visible to Owners only. | Ask an Owner. | — |
| 422 | `Organization name is required` | create or rename organization | Empty name. | Provide a name. | — |
| 403 | `Only an owner can archive an organization` | archive organization | Role too low. | Ask an Owner. | — |
| 409 | `Settle or cancel organization billing before archiving` | archive organization | An active subscription exists. | Cancel or settle billing first. | — |
| 403 | `Only an owner can restore an organization` | restore organization | Role too low. | Ask an Owner. | — |
| 403 | `Only an owner can close an organization` | close organization | Role too low. | Ask an Owner. | — |

### Session, Terms and membership

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 401 | `Not authenticated` | any signed-in action | Missing or expired session (sessions last 7 days). | Sign in again. | — |
| 403 | `Cross-origin write refused` | browser write from another site | Requests must come from the official app. | Use https://app.octopusprimeai.com or the mobile apps. | — |
| 428 | `Accept the Terms of Use before posting or uploading` | posting, uploading, scheduling | Terms of Use not accepted. | Accept the Terms in the app (I agree & continue). | Posting works. |
| 403 | `Insufficient role` | admin actions | Your role does not allow this. | Ask an Owner or Admin. | — |
| 403 | `Not a member of this organization` | any organization action | You are not an active member. | Accept the invitation or ask to be invited. | — |
| 403 | `Account unavailable` | any action after account changes | The account is deleted or deactivated. | Sign in again; contact an Owner if deactivated. | — |
| 409 | `Account changed` | any action | Account state changed during the request. | Retry. | — |
| 404 | `Organization not found` | any organization action | Unknown or inaccessible organization. | Switch to an organization you belong to. | — |

### Sign-in

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 401 | `Invalid Apple identity token` | Sign in with Apple | The Apple sign-in could not be verified. | Retry sign-in. | — |
| 401 | `Invalid Google identity token` | Sign in with Google | The Google sign-in could not be verified. | Retry sign-in. | — |
| 401 | `Verified Apple email required for new sign-in` | first Apple sign-in | New accounts need a verified e-mail from the provider. | Use an Apple ID with a verified e-mail, or sign in with Google. | — |
| 401 | `Verified Google email required for new sign-in` | first Google sign-in | New accounts need a verified e-mail. | Use a verified Google account. | — |
| 401 | `Apple account ownership conflict` | Apple sign-in | The Apple identity is linked differently than expected. | Sign in with the provider and e-mail used originally; contact support if it persists. | — |
| 401 | `Google account ownership conflict` | Google sign-in | As above. | As above. | — |
| 401 | `Apple account ownership changed; retry sign-in` | Apple sign-in | Linking changed during sign-in. | Retry sign-in. | — |
| 401 | `Google account ownership changed; retry sign-in` | Google sign-in | Linking changed during sign-in. | Retry sign-in. | — |
| 401 | `Ambiguous Apple account` | Apple sign-in | The identity matches more than one account. | Contact support. | — |
| 401 | `Ambiguous Google account` | Google sign-in | As above. | Contact support. | — |

### Messages

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | `Message is empty` | send message or schedule | No text and no files. | Write something. | — |
| 403 | `This conversation is blocked` | send in a DM | One of the two people blocked the other. | The blocker can unblock in Blocked users. | — |
| 404 | `Parent message not found` | reply in thread | The thread root is gone (for example past 30 days). | Post a new message. | — |
| 404 | `Channel not found` | any conversation action | Unknown conversation or no access. | Check membership. | — |
| 409 | `Client message ID already identifies a different message` | send message | The same client_message_id was reused with different content. | Use a new client_message_id for new content. | — |
| 422 | `Message cursor requires before and before_id` | history paging | Incomplete paging cursor. | Send both values. | — |
| 410 | `Source message expired` | retry of a delivery | The message is past the 30-day window. | Send a new message. | — |
| 404 | `Delivery not found` | retry of a delivery | Unknown delivery. | — | — |

### Direct messages

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | `Pick a person or an agent` | start a DM | Nothing selected. | Choose a person or an agent. | — |
| 400 | `Cannot DM yourself` | start a DM | You picked yourself. | Pick someone else. | — |
| 400 | `User is not an active member` | start a DM | The person is not an active member. | Invite or reactivate them. | — |
| 400 | `Agent is not available` | start an agent DM | The agent is inactive, revoked or no longer announced by its Gateway. | Make sure its Gateway is connected and the agent exists in OpenClaw. | Agent DM opens. |
| 403 | `Cannot start a conversation with this user` | start a DM | A block exists between the two people. | The blocker can unblock. | — |

### Plans and billing

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | `This organization's plan allows N active human(s)` | invite, accept invitation, reactivate member | The people limit of the plan (plus add-ons) is reached. | Owner/Admin adds Extra human add-ons or upgrades. | The action succeeds. |
| 409 | `This organization's plan allows N AI agent(s)` | new agent DM, add agent to channel | The agent limit is reached. | Owner/Admin adds Extra AI agent add-ons or upgrades (maximum 50). | The action succeeds. |
| 409 | `An organization can have at most 50 AI agents. Contact us to raise this limit.` | plan or add-on change | More than 50 agents requested. | Contact support@octopusprimeai.com. | — |
| 402 | `Your organization's subscription is inactive. An owner or admin must activate billing.` | posting after the trial ended or payment lapsed | No active subscription. | An Owner/Admin chooses a plan in the web app. | Posting works. |
| 400 | `Unknown plan` | checkout | Invalid plan. | Choose Starter, Pro or Business. | — |
| 409 | `A checkout for this organization is being opened. Try again in a moment.` | checkout | Another checkout is in progress. | Wait and retry. | — |
| 409 | `Subscription already active` | checkout | Already subscribed. | Change the plan instead. | — |
| 409 | `No billing account yet` | payment settings | No subscription created yet. | Choose a plan first. | — |
| 409 | `No active subscription. Choose a plan at checkout.` | plan change | No subscription to change. | Choose a plan. | — |

### Channels

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | `Channel agent limit (5) reached` | add agent to channel | The channel already has 5 agents. | Remove an agent or use another channel. | — |
| 403 | `Manager is not assigned to this channel` | channel management | Managers manage only channels they are in. | Ask an Owner/Admin. | — |
| 400 | `Invalid channel type` | create channel | Unsupported type. | — | — |
| 409 | `Direct messages cannot be administered as channels` | channel management on a DM | DMs have no channel settings. | — | — |
| 409 | `Restore the channel before editing it` | edit archived channel | The channel is archived. | Restore it first. | — |
| 422 | `Channel name is required` | create or rename channel | Empty name. | Provide a name. | — |
| 409 | `Organization-wide channels cannot be private` | channel settings | #announcements is organization-wide. | — | — |
| 409 | `Organization-wide channels cannot be archived` | archive channel | #announcements cannot be archived. | — | — |
| 422 | `No channel changes supplied` | channel update | Nothing changed. | — | — |
| 400 | `User is not an active member of this organization` | add member to channel | The person is not an active member. | Invite or reactivate them first. | — |
| 403 | `Only an owner or admin can assign an Owner, Admin, or Manager to a channel` | channel membership | Managers cannot add elevated roles. | Ask an Owner/Admin. | — |
| 403 | `Only an owner or admin can unassign an Owner, Admin, or Manager from a channel` | channel membership | Managers cannot remove elevated roles. | Ask an Owner/Admin. | — |
| 409 | `Channel changed` | channel update | Concurrent change. | Reload and retry. | — |
| 404 | `Agent not found` | agent actions | Unknown agent. | Check the agent list in OpenClaw Agents. | — |

### Invitations

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | `User is already a member` | invite | Already in the organization. | — | — |
| 409 | `An invitation is already pending for this email` | invite | An open invitation exists. | Wait for acceptance or withdraw it first. | — |
| 404 | `Invitation not found or already used` | accept invitation | Withdrawn, used or unknown. | Ask for a new invitation. | — |
| 403 | `This invitation was sent to a different email` | accept invitation | Signed in with another address (common with Apple Hide My Email). | Sign in with the invited address, or ask to invite the address you use. | — |
| 410 | `Invitation expired` | accept invitation | Older than 14 days. | Ask for a new invitation. | — |
| 403 | `Ownership invitation lacks verified authority; request a new owner-issued invitation` | accept Owner invitation | The Owner invitation is not valid. | Ask a current Owner to invite you again. | — |
| 409 | `This owner invitation was withdrawn because the person who sent it is no longer an owner of this organization. Ask a current owner to invite you again.` | accept Owner invitation | The inviter is no longer an Owner. | Ask a current Owner. | — |

### Roles and members

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | `Invalid role` | role change | Unknown role. | Use owner, admin, manager or member. | — |
| 409 | `Cannot remove the sole active owner` | role change or removal | The organization must keep one Owner. | Make someone else Owner first. | — |
| 409 | `Cannot deactivate the sole owner` | deactivate member | As above. | Make someone else Owner first. | — |
| 403 | `Only an owner can assign ownership` | role change | Admins cannot grant Owner. | Ask an Owner. | — |
| 403 | `Only an owner can change ownership` | role change | Admins cannot change an Owner. | Ask an Owner. | — |
| 400 | `Invalid status` | member status change | Unknown status. | — | — |
| 409 | `Deleted accounts cannot be reactivated` | reactivate member | The person deleted their account. | Invite their new account. | — |
| 404 | `Member not found` | member actions | Unknown member. | — | — |

### Account deletion

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | `You are the only owner of '<org>'. Make another member an owner before deleting your account.` | delete account | Sole Owner of an organization with other active members. | Make another member an Owner, then delete. | Deletion succeeds. |
| 409 | `Settle or cancel billing for '<org>' before deleting your account.` | delete account | Active billing on an organization you would close. | Cancel or settle billing first. | Deletion succeeds. |
| 409 | `A checkout is open for '{name}'. Try again after it expires in {N minute(s)}.` | delete account | A checkout session is open. | Wait the stated time. | Deletion succeeds. |
| 409 | `Membership changed; retry account deletion` | delete account | Membership changed during deletion. | Retry. | Deletion succeeds. |

### Scheduled messages

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | `Messages can be scheduled only in a channel or an agent direct message` | create schedule | Person-to-person DM. | Use a channel or agent DM. | — |
| 400 | `Choose a template or write a message` | create schedule | Neither text nor template. | Provide one. | — |
| 400 | `A scheduled message can be at most 4000 characters` | create schedule | Text over 4,000 characters. | Shorten it. | — |
| 400 | `Invalid start time` | create schedule | Unparseable time. | Pick a valid time. | — |
| 400 | `Choose a time in the future` | create schedule | Start time not at least 30 s ahead. | Pick a time further ahead. | — |
| 400 | `Choose when to send the message` | create schedule | No time given for a one-time schedule. | Pick a time. | — |
| 400 | `Start time is too far out (max 90 days)` | create schedule | More than 90 days ahead. | Pick an earlier time. | — |
| 409 | `This organization already has 20 scheduled messages. Delete one before adding another.` | create schedule | 20 active or paused schedules exist. | Delete one. | — |
| 409 | `Client schedule ID already identifies a different schedule` | create schedule | Reused id with different content. | Retry as a new schedule. | — |
| 409 | `Only an active schedule can be paused` | pause | Not active. | — | — |
| 403 | `Only the person who created this schedule can resume it` | resume | Not the creator. | Ask the creator, or create a new schedule. | — |
| 409 | `Only a paused schedule can be resumed` | resume | Not paused. | — | — |
| 409 | `This one-time schedule's time has passed` | resume | The one-time slot is in the past. | Create a new schedule. | — |
| 422 | `Status must be paused or active` | update schedule | Invalid status value. | — | — |
| 404 | `Template not found` | schedule from template | Template deleted. | Pick another template. | — |
| 404 | `Schedule not found` | schedule actions | Deleted or unknown. | — | — |

### Report and block

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | `You can't report your own message` | report | — | — | — |
| 409 | `A moderator already removed this message` | report | Already handled. | — | — |
| 400 | `You can't report yourself` | report person | — | — | — |
| 404 | `Person not found in this conversation` | report person | The person is not in that conversation. | — | — |
| 404 | `Message not found` | report message | Message gone (for example past 30 days). | — | — |
| 400 | `Cannot block yourself` | block | — | — | — |
| 404 | `Person not found` | block | Unknown person. | — | — |
| 400 | `Agents can't be blocked. Report the message instead, or ask an owner or admin to remove the agent.` | block an agent | Agents are not blockable. | Report the message or ask an Owner/Admin to remove the agent from the channel. | — |

### Files

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | `Upload one file per request` | upload | More than one file in one upload. | Upload files one by one. | — |
| 413 | `File "<name>" is larger than 5 MB` | upload | Over 5 MB. | Shrink or split the file. | — |
| 400 | `A message can include at most 5 files; this one has N` | send message | More than 5 attachments. | Send in several messages. | — |
| 400 | `Duplicate attachments are not allowed` | send message | Same file attached twice. | Remove the duplicate. | — |
| 400 | `One or more attachments are unavailable in this channel` | send message | Attachment uploaded elsewhere or expired. | Upload again in this conversation. | — |
| 400 | `This file type is not allowed` | upload | Blocked type (executables, scripts, HTML, SVG, XML). | Use an allowed format or share as text. | — |
| 400 | `Unsupported file type` | upload | Unrecognized type. | Use an allowed format. | — |
| 410 | `This file has expired` | download | Older than 7 days. | Ask the sender to share it again. | — |
| 404 | `File not found` | download | Unknown file. | — | — |
| 403 | `Forbidden` | download | No access to that conversation. | — | — |

### Search

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 422 | `Search query is required` | search | Empty query. | Type a query. | — |

### Notification settings

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 422 | `mode must be one of all\|mentions\|mute` | notification settings | Invalid mode. | Use all, mentions or mute. | — |
| 422 | `time must be HH:MM (24-hour)` | quiet hours | Invalid time format. | Use HH:MM. | — |
| 422 | `timezone is required` | quiet hours | Missing time zone. | Provide an IANA time zone. | — |
| 422 | `invalid IANA timezone` | quiet hours | Unknown time zone. | Use a name like America/Phoenix. | — |

### Voice

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | `Recording too short — try again` | dictation | Clip under 2 KB. | Record longer. | — |
| 413 | `Audio exceeds the 25 MB limit` | dictation | Clip over 25 MB. | Record a shorter clip. | — |
| 502 | `Could not transcribe audio` | dictation | Transcription failed. | Retry. | — |
| 400 | `Nothing to read aloud` | read aloud | Message has no text. | — | — |
| 502 | `Could not generate audio` | read aloud | Speech generation failed. | Retry. | — |

### Health Watch

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 404 | `Health Watch incident not found` | acknowledge incident | Unknown or expired incident (finished incidents are kept 7 days). | Refresh Health Watch. | — |
| 409 | `Health Watch incident is already terminal` | acknowledge incident | The incident already closed. | Nothing to do. | — |

### Service health

| HTTP | Exact `detail` | Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 503 | `Service unavailable` | GET /api/health/ready | The service is not ready (starting or a dependency is down). | Wait and retry. | GET /api/health/ready returns {"status":"ready"}. |
| 503 | `Database unavailable` | any request | Temporary storage outage. | Retry after a short wait. | — |

## App messages

Banners, toasts and inline messages in the web and mobile apps.

| Exact text | Where | Cause | Fix | Verify |
|---|---|---|---|---|
| `Live updates off — checking for new messages every few seconds` | Web banner | The app is refreshing open conversations every few seconds instead of receiving live pushes. | Nothing; new messages still appear within seconds. | — |
| `Live updates off · open chats refresh every few seconds` | iPhone banner | As above. | Nothing. | — |
| `Reconnecting…` | Web banner | A refresh of the conversation failed. | Wait; it clears on the next successful refresh. Check your internet connection if it stays. | — |
| `Could not load connectors` | OpenClaw Agents dialog (with Retry) | The connector list could not be loaded. | Retry; sign in again if your session expired. | — |
| `Could not create connector` | OpenClaw Agents dialog | Connect OpenClaw failed (or the service detail is shown instead). | Retry; check you are Owner/Admin. | — |
| `Could not create a new setup code` | OpenClaw Agents dialog | New setup code failed. | Retry; check you are Owner/Admin. | — |
| `Could not revoke connector` | OpenClaw Agents dialog | Revoke failed. | Retry; check you are Owner/Admin. | — |
| `Connector revoked` | OpenClaw Agents dialog (success) | The connector was revoked. | Disable or uninstall the plugin on that Gateway to stop its reconnect attempts. | — |
| `Could not copy. Select the text and copy it manually.` | OpenClaw Agents dialog | Clipboard access failed. | Use View or manually copy the prompt. | — |
| `A valid HTTPS backend address is required to prepare connection instructions.` | OpenClaw Agents dialog | The app could not build the setup prompt. | Reload the web app; contact support if it persists. | — |
| `Could not load agents.` | iPhone agents list (with Retry) | The agent list could not be loaded. | Retry. | — |
| `No agents connected` | iPhone agents list | No connected Gateway has announced agents. | Connect a Gateway (web app) and check it is READY. | — |
| `"{name}" is {size} — over the 5 MB limit, so it was not attached.` | Composer | File over 5 MB. | Use a smaller file. | — |
| `"{name}" is too large to upload (the limit is 5 MB), so it was not attached.` | Composer | Upload refused as too large. | Use a smaller file. | — |
| `This file has expired.` | Message attachment | File older than 7 days. | Ask the sender to share it again. | — |
| `You cannot post here` | Composer | No permission to post in this conversation. | Ask a channel manager or Owner/Admin. | — |
| `Accept the Terms of Use before posting` | Composer | Terms not accepted. | Accept the Terms (I agree & continue). | — |
| `Could not send message` | Composer | Sending failed. | Retry; check connection and subscription status. | — |
| `Your free trial has ended` | Billing / paywall | The 7-day trial ended without a plan. | An Owner/Admin chooses a plan in the web app. | Posting works. |
| `Subscription inactive` | Billing / paywall | No active subscription. | An Owner/Admin chooses or fixes the plan. | Posting works. |
| `Access is paused for this organization. Please ask an owner or admin to choose a plan.` | Paywall (members) | Trial ended or subscription inactive. | Ask an Owner/Admin. | Posting works. |
| `Payment failed — please update your card` | Billing | A payment failed; the 7-day grace period runs. | Owner/Admin updates the payment method in the web app. | Notice disappears. |
| `Access paused — trial ended. Open Settings.` | iPhone banner | Trial ended. | Owner/Admin chooses a plan on the web. | Posting works. |
| `Access paused — subscription inactive. Open Settings.` | iPhone banner | Subscription inactive. | Owner/Admin fixes billing on the web. | Posting works. |
| `Enter a valid email address (name@company.com).` | Invite people | Malformed address. | Correct the address. | — |
| `That email domain can’t receive invitations. Use a real work email.` | Invite people | The domain is not accepted for invitations. | Use another address. | — |
| `Your account was deleted` | Sign-in screen | You deleted your account; all sessions ended. | Signing in again starts a new, empty account. | — |
| `You have been signed out on every device. Signing in again starts a new account.` | Sign-in screen after deletion | Account deletion. | — | — |
| `Health Watch is available only to an Owner or Admin of an active organization.` | iPhone Health Watch | Role too low or organization inactive. | Ask an Owner/Admin. | — |
| `No gateways are connected.` | Health Watch | No connector exists. | Connect a Gateway. | — |
| `Microphone access was denied` | Dictation | Microphone permission missing. | Allow microphone access for the app or browser. | — |
| `Recording failed — try again` | Dictation | Recording error. | Retry. | — |
| `Didn't catch that — try again` | Dictation | No speech recognized. | Speak again. | — |
| `Transcription failed` | Dictation | Transcription error. | Retry. | — |
| `Playback failed` | Read aloud | Audio playback error. | Retry. | — |
| `Could not read aloud` | Read aloud | Speech generation error. | Retry. | — |
| `Message from a blocked user hidden.` | Conversation | You blocked the sender. | Unblock in Blocked users if wanted. | — |

## When the fix does not work

1. Collect a sanitized diagnostics bundle on the Gateway host: `openclaw triage --non-interactive`. It collects diagnostics without launching an agent; the archive excludes secrets, tokens, raw chat payloads and raw logs (OpenClaw docs: cli/triage).
2. E-mail support@octopusprimeai.com with the exact error text, the time it happened (with time zone), what you already tried, and the bundle. Never include setup codes, connector credentials or session tokens.