Chat API returns HTTP 400 "Don't know how to map UsageDetails" error

[mjpraxis]

Which component is this issue related to?

Other / Not sure

Which Umbraco AI version are you using? (Please write the exact version, example: 10.1.0)

1.10.0

Bug summary

Disclaimer: This description is made with help of Copilot.

Following the documentation regarding how to make a simple chat request using the the default profile.
https://github.com/umbraco/Umbraco.AI/blob/dev/docs/public/frontend/README.md

My code - simplyfied:

const messages: UaiChatMessage[] = [
    {
        role: 'user',
        content: `Generer en kort opsummering af følgende indhold:\n\n${output}`
    }
];
const chatController = new UaiChatController(this);

const { data, error } = await chatController.complete(messages);

When calling the Chat API endpoint (POST /umbraco/ai/management/api/v1/chat/complete), the response returns HTTP 400 with the following error:

{ "detail": "Don't know how to map Microsoft.Extensions.AI.UsageDetails to Umbraco.AI.Web.Api.Common.Models.UsageModel.", "status": 400, "title": "Chat completion failed" }

Root Cause

A wrong namespace import in UmbracoBuilderExtensions.cs causes the correct mapper to not be registered.

There are two different CommonMapDefinition classes in different namespaces:

• Umbraco.AI.Web.Api.Common.Mapping.CommonMapDefinition — HAS the UsageDetails → UsageModel mapping ✅
• Umbraco.AI.Web.Api.Management.Common.Mapping.CommonMapDefinition — does NOT have it ❌

Currently, only the second one is being imported, so the UsageDetails mapper is never registered.

The Fix

File: Umbraco.AI/src/Umbraco.AI.Web/Configuration/UmbracoBuilderExtensions.cs

Add this import after line 10:

using Umbraco.AI.Web.Api.Common.Mapping;

So the imports section becomes:

using Umbraco.AI.Web.Api.Common.Configuration;
using Umbraco.AI.Web.Api.Common.Mapping;  // ✅ ADD THIS LINE
using Umbraco.AI.Web.Api.Common.Models;
using Umbraco.AI.Web.Api.Management.Analytics.Usage.Mapping;
using Umbraco.AI.Web.Api.Management.AuditLog.Mapping;
using Umbraco.AI.Web.Api.Management.Chat.Mapping;
using Umbraco.AI.Web.Api.Management.Common.Mapping;
// ... rest of imports

Impact

- Breaks: Chat API endpoint when returning usage statistics
- Workaround: Use Prompt or Agent endpoints instead
- Note: Built-in chat features work because they use different endpoints

Steps to Reproduce

1. Create a custom TypeScript component in Umbraco backoffice
2. Instantiate UaiChatController and call complete(messages)
3. Send a message to the chat API
4. Observe HTTP 400 error with "Don't know how to map UsageDetails" message

### Specifics

_No response_

### Steps to reproduce

Guess you can just try your sample from the documentation

https://github.com/umbraco/Umbraco.AI/blob/dev/docs/public/frontend/README.md

### Expected result / actual result

_No response_

### Dependencies

_No response_

[mattbrailsford]

Thanks for the detailed write-up — diagnosis was spot on. PR up in #156.

One small twist: just adding the using would have caused a CS0104 ambiguity, since both namespaces contain a class literally named CommonMapDefinition. So instead of touching the import order, I renamed the Common-namespace one to UsageDetailsMapDefinition (specific to what it actually maps) and registered it explicitly. That removes the silent-binding trap entirely. Also added a regression test on ChatResponse → ChatResponseModel so this can't slip back unnoticed.

[mjpraxis]

Do you have an idea when the NuGet package Umbraco.AI.Web will be updated with this fix?

[mattbrailsford]

Hey @mjpraxis we actually made a release yesterday just before your issue was raised. We tend to wait at least a week after a release to see if other bugs come in to group and release together.

In the mean time, if you drop this in your C# project, it should fix it temporarily

  using Microsoft.Extensions.AI;
  using Umbraco.AI.Web.Api.Common.Models;
  using Umbraco.Cms.Core.Composing;
  using Umbraco.Cms.Core.DependencyInjection;
  using Umbraco.Cms.Core.Mapping;

  public class UsageDetailsMappingFixComposer : IComposer
  {
      public void Compose(IUmbracoBuilder builder)
      {
          builder.WithCollectionBuilder<MapDefinitionCollectionBuilder>()
              .Add<UsageDetailsMappingFix>();
      }
  }

  public class UsageDetailsMappingFix : IMapDefinition
  {
      public void DefineMaps(IUmbracoMapper mapper)
      {
          mapper.Define<UsageDetails, UsageModel>(
              (_, _) => new UsageModel(),
              (source, target, _) =>
              {
                  target.InputTokens = source.InputTokenCount;
                  target.OutputTokens = source.OutputTokenCount;
                  target.TotalTokens = source.TotalTokenCount;
              });
      }
  }

[mjpraxis]

@mattbrailsford thanks for the temp fix hint. It works perfectly.