Word Online insertComment API error NotAllowed

Question

Inserting comments via API (in JS, Range.insertComment) was consistently working in Word Desktop but consistently failing in Word Online.

According to https://learn.microsoft.com/en-us/javascript/api/word/word.range?view=word-js-preview#word-word-range-insertcomment-member(1), Range.insertComment should work, since it is API set: WordApi 1.4 which is "Supported" by " Office on the web".

To help debug, I added these diag logs:

      1461 -      // TODO(remove): temporary diagnostic for the NotAllowed error on Word Online.                                                                              
      1462 -      // Logs what the host claims about comments-API support before the call, and                                                                                
      1463 -      // captures the full documented error payload (debugInfo) if insertComment throws.                                                                          
      1464 -      debugLog(`[diag] host=${Office.context.host} platform=${Office.context.platform}`);                                                                         
      1465 -      debugLog(                                                                                                                                                   
      1466 -        `[diag] isSetSupported(WordApi,1.4)=${Office.context.requirements.isSetSupported('WordApi', '1.4')}`,                                                     
      1467 -      );

      1471 -      try {                                                                                                                                                       
      1472 -        range.insertComment(commentText);                                                                                                                         
      1473 -        await context.sync();                                                                                                                                     
      1474 -      } catch (error) {                                                                                                                                           
      1475 -        debugError(                                                                                                                                               
      1476 -          '[diag] insertComment failed; debugInfo:',                                                                                                              
      1477 -          JSON.stringify(error?.debugInfo, null, 2),                                                                                                              
      1478 -        );                                                                                                                                                        
      1479 -        throw error;                                                                                                                                              
      1480 -      } 

Which yielded

  [7:01:21 PM] [diag] host=Word platform=OfficeOnline                                                                                                                                
  [7:01:21 PM] [diag] isSetSupported(WordApi,1.4)=true                                                                                                                               
  [7:01:21 PM] [diag] insertComment failed; debugInfo: { "code": "NotAllowed", "message": "The action isn't supported by Word in a browser. Check the                                
  OfficeExtension.Error.debugInfo for more information.", "errorLocation": "Range.insertComment", "statement": "var insertComment = range.insertComment(...);",                      
  "surroundingStatements": [ "var v = context.root._getObjectByReferenceId(\"{135f5ce2-52d7-435c-8474-cb5a198e8a63}{22}\");", "var range = v.getRange();", "// Instantiate {range}", 
  "// >>>>>", "var insertComment = range.insertComment(...);", "// <<<<<", "// Instantiate {insertComment}" ], "fullStatements": [ "Please enable config.extendedErrorLogging to     
  see full statements." ] }

Answer 1

Range.insertComment is part of the WordApi 1.4 requirement set and is supported on Word on the web, but Word on the web also has additional, online‑only behavior and preview APIs that are surfaced through the WordApiOnline and preview requirement sets.

Key points from the platform behavior and docs:

1. Range.insertComment itself
   • The method is documented on Word.Range with [API set: WordApi 1.4] and is therefore included in the numbered requirement set.
   • Word on the web supports WordApi 1.4, which is why Office.context.requirements.isSetSupported('WordApi', '1.4') correctly returns true.
   • The NotAllowed error is not a signal that the API is unknown; it indicates that the host (Word in a browser) is blocking the specific action in the current environment or configuration.
2. Online‑only and preview behavior
   • Word on the web has a special WordApiOnline requirement set that contains features only available online. This set is a superset of the latest numbered requirement set and is considered production only for Word on the web.
   • Preview APIs and eventing around comments (for example, onCommentAdded, onCommentChanged, onCommentSelected, onCommentDeselected on Word.Range) are explicitly marked as preview only and must not be used in production. These are surfaced under the WordApi BETA requirement set and can behave differently or be restricted.
3. Why isSetSupported('WordApi', '1.4') can be true but the call still fails
   • isSetSupported only tells that the host recognizes and exposes the API set; it does not guarantee that every call will be allowed in every scenario.
   • Word on the web can still reject a particular operation at runtime with NotAllowed if the action is not permitted in that context (for example, due to current document mode, feature rollout state, or internal restrictions in the browser host).
   • The error payload shown (code: "NotAllowed", errorLocation: "Range.insertComment", message saying the action is not supported by Word in a browser) is the expected way the host reports such a runtime restriction.
4. Recommended handling pattern
   • Keep using Office.context.requirements.isSetSupported('WordApi', '1.4') to gate use of insertComment at a high level.
   • Additionally, handle NotAllowed from Range.insertComment explicitly and fall back to an alternative behavior (or disable the feature) when running on Office.context.platform === 'OfficeOnline'.
   • Do not rely on preview comment events (onCommentAdded, onCommentChanged, onCommentSelected, onCommentDeselected) in production, as they are marked as WordApi BETA and may change or be unavailable.

In summary, the behavior observed is consistent with the platform: Word on the web advertises support for WordApi 1.4, but may still block Range.insertComment in some environments with NotAllowed. The add‑in should both check the requirement set and be prepared to catch and handle NotAllowed at runtime when running in a browser.

---

References:

• Word JavaScript API online-only requirement set
• What's new in Word JavaScript API 1.4
• Word.Range class
• Word JavaScript API requirement sets

Answer 2

Hi @TJ Jann
Please note that we're not Microsoft support, this is a user-to-user support forum. Moderators here don’t have backend access to Microsoft systems, so we can only provide technical guidance based on public resources and experiences.

Based on the information you've shared, the behavior appears inconsistent with the documented support information. Your logs show that:

• Office.context.requirements.isSetSupported('WordApi', '1.4') returns true, indicating that Word Online reports support for the API set that includes Range.insertComment().
• However, the call to Range.insertComment() fails with a NotAllowed error, specifically at errorLocation: "Range.insertComment".

Since the same code works consistently in Word Desktop but fails in Word Online, this suggests a platform-specific limitation or incomplete implementation in Word Online rather than an issue with your code.

It’s important to note that support for a requirement set such as WordApi 1.4 does not always guarantee that every API within that set is fully implemented or enabled across all hosts. In some cases, individual APIs may be partially supported or restricted in certain environments, such as Office on the web.

I recommend opening an issue with the Office.js team on GitHub repository where developers and contributors actively working with Office.js can share additional insights and guidance. If you open a GitHub issue, feel free to share the link here, as it may help other developers encountering similar behavior.

References: Participating in a discussion - GitHub Docs   

Thank you for your patience and understanding, and I’m sorry we can’t resolve this directly here. Redirecting you ensures you’ll connect with the right support team who can provide the help you need.

---

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.