diff --git a/errors/codes/90011.md b/errors/codes/90011.md
new file mode 100644
index 00000000..646f2832
--- /dev/null
+++ b/errors/codes/90011.md
@@ -0,0 +1,20 @@
+---
+code: 90011
+identifier: channel_release_invalid_state
+title: Channel released while not detached
+summary: A request to release a channel was rejected because the channel was not in the initialized, detached or failed state, so it could still receive messages from Ably.
+---
+
+## What you should do
+
+Detach the channel and wait for the detach to complete before releasing it. Releasing only removes the SDK's reference to the channel so that it can be garbage collected; it does not detach the channel for you.
+
+## Why it happens
+
+The SDK only releases a channel once there is no possibility of it receiving any further messages, which is the case when it is in one of the [channel states](https://ably.com/docs/channels/states) initialized, detached or failed. A channel that is attaching, attached, detaching or suspended can still receive messages, and releasing it would leave messages arriving for a channel that the SDK no longer tracks.
+
+Earlier SDK versions detached the channel automatically before releasing it. If you see this error after upgrading, detach the channel explicitly first.
+
+## What you'll see
+
+The error is raised by the SDK rather than returned by Ably, with code 90011 and HTTP status 400. The message names the channel's current state.
diff --git a/protocol/errors.json b/protocol/errors.json
index ae7d6f93..00d2a4b0 100644
--- a/protocol/errors.json
+++ b/protocol/errors.json
@@ -992,6 +992,11 @@
       "title": "Too many channels",
       "summary": "An operation was rejected because it would exceed the maximum number of channels permitted, either the channels attached to a single connection or those included in a single batch request."
     },
+    "90011": {
+      "identifier": "channel_release_invalid_state",
+      "title": "Channel released while not detached",
+      "summary": "A request to release a channel was rejected because the channel was not in the initialized, detached or failed state, so it could still receive messages from Ably."
+    },
     "90021": {
       "identifier": "rate_limit_exceeded_account_channel_creation",
       "title": "Account-wide channel creation rate exceeded",