microsoft/semantic-kernel · error · AgentThreadOperationException

The message could not be added to the thread due to an error

Error message

The message could not be added to the thread due to an error response from the service.

What it means

Thrown by AzureAIAgentThread.OnNewMessageInternalAsync when AgentThreadActions.CreateMessageAsync fails with a RequestFailedException. This occurs while adding a user/assistant message to the Azure AI thread. The service error is wrapped in AgentThreadOperationException. Note: messages generated by the same agent are skipped (detected via Metadata['ThreadId']), so this only fires for messages that genuinely need to be posted.

Source

Thrown at dotnet/src/Agents/AzureAI/AzureAIAgentThread.cs:135

            throw new AgentThreadOperationException(ErrorMessage, ex);
        }
    }

    /// <inheritdoc />
    protected override async Task OnNewMessageInternalAsync(ChatMessageContent newMessage, CancellationToken cancellationToken = default)
    {
        const string ErrorMessage = "The message could not be added to the thread due to an error response from the service.";

        // If the message was generated by this agent, it is already in the thread and we shouldn't add it again.
        if (newMessage.Metadata == null || !newMessage.Metadata.TryGetValue("ThreadId", out var messageThreadId) || !string.Equals(messageThreadId, this.Id))
        {
            try
            {
                await AgentThreadActions.CreateMessageAsync(this._client, this.Id!, newMessage, cancellationToken).ConfigureAwait(false);
            }
            catch (RequestFailedException ex)
            {
                throw new AgentThreadOperationException(ErrorMessage, ex);
            }
            catch (AggregateException ex)
            {
                throw new AgentThreadOperationException(ErrorMessage, ex);
            }
        }
    }

    /// <summary>
    /// Asynchronously retrieves all messages in the thread.
    /// </summary>
    /// <param name="sortOrder">The order to return messages in.</param>
    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
    /// <returns>The messages in the thread.</returns>
    /// <exception cref="InvalidOperationException">The thread has been deleted.</exception>
    [Experimental("SKEXP0110")]
    public async IAsyncEnumerable<ChatMessageContent> GetMessagesAsync(ListSortOrder? sortOrder = default, [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Inspect the InnerException (RequestFailedException) for the HTTP status and error details.
  2. For 429, implement retry with exponential backoff on the agent invocation.
  3. For 401/403, refresh credentials.
  4. Validate message content size and format before sending.
  5. Ensure the thread has not been deleted externally.
Defensive patterns

Strategy: retry

Try / catch

try
{
    await agent.InvokeAsync(messages, thread, ct);
}
catch (AgentThreadOperationException ex) when (ex.InnerException is RequestFailedException rfe)
{
    _logger.LogError("Message add failed: {Status}", rfe.Status);
    if (rfe.Status == 429) { /* retry */ }
    else throw;
}

Prevention

When it happens

Trigger: Adding a new ChatMessageContent to the thread via the framework's OnNewMessageInternalAsync, and the underlying CreateMessageAsync call to Azure AI Agents fails with a non-404 RequestFailedException. Causes: auth failure, rate limiting, invalid message format, thread not found on service side, or service errors.

Common situations: Token expiry during a long conversation. Rate limiting on message creation. Message content too large or in an unsupported format. Thread was deleted out-of-band (on the portal) but not locally. Service transient errors during high-load periods.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/f05d6eb82ece57a6. Report an issue: GitHub.