Kipt

Your prompts and skills, one keystroke away.

Explore

Azure messaging skill: troubleshoot Service Bus and Event Hubs SDK errors

The Azure messaging skill helps coding agents fix Service Bus and Event Hubs SDK errors: AMQP drops, lock lost, auth and checkpoints. How to install and use it.

By the Kipt team · Updated 27 October 2026

Source: microsoft/azure-skills · Maintainer: Microsoft · License: MIT · Checked: 27 October 2026

What is the Azure messaging skill?

The Azure messaging skill is Microsoft's troubleshooting guide for Azure Event Hubs and Azure Service Bus client code, written for coding agents. When an SDK throws a connection error, loses a message lock or stops receiving, it gives the agent a diagnosis order and points it to error tables for your language.

The description opens: "Troubleshoot and resolve issues with Azure Messaging SDKs for Event Hubs and Service Bus. Covers connection failures, authentication errors, message processing issues, and SDK configuration problems." The trigger list that follows is long and specific, from "message lock lost" and "AMQP error" to "event hub checkpoint" and "service bus dead letter".

The skill ships in microsoft/azure-skills, the Azure Skills Plugin, under "Work across data, AI, identity, and platform services" in the README. Its frontmatter gives version 1.2.1, author Microsoft and license MIT.

As of 27 October 2026, its skills.sh page listed about 558,000 installs (snapshot, 27 October 2026).

What does it do?

The folder holds a single SKILL.md of about 3.3 KB. It sets the workflow and tools, then hands off to guides that live in the azure-diagnostics skill.

The diagnosis workflow has six steps:

  1. Identify the SDK and version from your prompt, and ask later if it matters.
  2. Check namespace health with the Azure MCP resource health tool.
  3. Match the error message against the language guide.
  4. Search Microsoft Learn through the Azure MCP documentation tool.
  5. Check configuration: connection string, entity name, consumer group.
  6. Recommend a fix, "citing documentation found".

The MCP tools are mcp_azure_mcp_eventhubs and mcp_azure_mcp_servicebus to list namespaces, hubs, consumer groups, queues, topics and subscriptions, plus monitor for KQL log queries, resourcehealth and documentation.

The guides. The SKILL.md says: "Connectivity, SDK, and auth troubleshooting guides are located in the azure-diagnostics skill under troubleshooting/messaging/." That folder in the repo holds a routing README plus:

File What it covers
service-troubleshooting.md Ports, firewalls, VNets, proxies, WebSockets, batch limits, socket exhaustion
auth-best-practices.md Managed identity in production, DefaultAzureCredential for local development only
4 Event Hubs guides Python, Java, JavaScript and .NET errors, retries, logging, checkpointing
4 Service Bus guides Python, Java, JavaScript and .NET errors, lock renewal, sessions, dead letters

A connectivity probe script, test-messaging-connectivity.sh with a PowerShell twin, sits in azure-diagnostics too. Its header says it checks DNS, HTTPS and the messaging ports, and that "A blocked port is a valid diagnostic result, not a failure".

What the guides say. A few examples. For a client that can't connect, open AMQP ports 5671 and 5672 and HTTPS 443, plus 9093 for the Event Hubs Kafka endpoint, or switch to AMQP over WebSockets on 443. Batches over 1 MB fail even with Premium large message support, so send big messages one by one. Treat clients as singletons, because each new client opens a new AMQP connection. In Python, register messages with AutoLockRenewer to avoid MessageLockLostError, and inspect dead letters with sub_queue=ServiceBusSubQueue.DEAD_LETTER. For Event Hubs checkpointing, disable soft delete and blob versioning on the checkpoint storage account, and expect HTTP 412 and 409 responses during partition ownership changes.

The ports, the 1 MB batch limit and the lock-lost behavior line up with Microsoft's Service Bus troubleshooting guide and Event Hubs connectivity guide.

How do you install the Azure messaging skill?

The repo README documents several routes. The full plugin is the better fit here: it brings the Azure MCP tools the workflow calls and the azure-diagnostics skill that holds the guides.

Claude Code: the Azure Skills Plugin. Run inside Claude Code:

/plugin install azure@claude-plugins-official

Or run /plugin and search for "azure". See Claude Code plugins and Claude Code MCP.

GitHub Copilot CLI:

/plugin marketplace add microsoft/azure-skills
/plugin install azure@azure-skills

Codex, Cursor and Gemini CLI. For Codex, the README says to run codex plugin marketplace add microsoft/azure-skills, then install azure from /plugins. For Cursor, use the Cursor Marketplace or Settings, then Plugins. For Gemini CLI, run gemini extensions install https://github.com/microsoft/azure-skills. See Codex skills and Cursor skills.

Skill files only. skills.sh lists npx skills add https://github.com/microsoft/azure-skills --skill azure-messaging, which copies just the 3.3 KB SKILL.md. To keep the guides it refers to, add azure-diagnostics in the same command; the skills CLI accepts --skill more than once:

npx skills add https://github.com/microsoft/azure-skills --skill azure-messaging --skill azure-diagnostics

Prerequisites, per the README: an Azure account or subscription, Node.js 18 or later on your PATH (npx starts the MCP servers), and the Azure CLI signed in with az login. The skills CLI used for the skill-only route needs Node.js 22.20 or later, per its README.

How do you use it?

Paste the error and say which SDK you use. The skill is model-invoked, so an error message or a phrase like "service bus queue issue" loads it.

Example prompts (suggestions, not from the repo):

  • Our Python Service Bus consumer keeps throwing MessageLockLostError on long jobs. Here's the handler. Fix it.
  • The Event Hubs processor in our .NET worker stops receiving after a few hours. Help me find out why.
  • Our Java app can't connect to Service Bus from the corporate network. What should I check?
  • We're seeing duplicate events after every deploy of our Event Hubs consumer in Node.js.
  • Turn on debug logging for azure-eventhub in Python so I can see the AMQP frames.

Expect a health check on the namespace, questions about your network or config, and a code change, often logging, a retry setting or lock renewal.

Tips and limits

From the repo, Microsoft Learn and skills.sh, not from testing:

  • The skill alone is thin. Kipt's reading of the files: installed without azure-diagnostics, the agent has the workflow and tool names but not the error tables, since those live in the azure-diagnostics folder. Install both, or the plugin.
  • One port typo. The WebSockets lines in the .NET Service Bus and .NET Event Hubs guides give the AMQP ports as 5761 and 5762. Microsoft's troubleshooting guides and the skill's own service guide say 5671 and 5672.
  • Current SDKs only. The guides cover the current packages, such as Azure.Messaging.ServiceBus and azure-messaging-servicebus. Microsoft's Service Bus guide says the older WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus and com.microsoft.azure.servicebus libraries were retired on 30 September 2026, so migrate rather than troubleshoot them.
  • Production auth. The auth guide's rule: "Use managed identities and Azure RBAC in production. Reserve DefaultAzureCredential for local development only."
  • Audits. On skills.sh, Gen Agent Trust Hub rated azure-messaging Pass (Safe) on 15 September 2026, describing it as documentation only with no code. Socket and Snyk both rated it Pass on 15 September 2026. The probe script ships in azure-diagnostics, which has its own audits.

The MIT License lets you copy and change the skill as long as you keep Microsoft's copyright and license notices.

Save it in your Kipt library

A merged copy is handy: the routing SKILL.md plus only the guides for your language, in one folder, with your namespace naming and retry defaults added. In Kipt, open Skills and paste a GitHub folder link into the import box, or drop a folder or a .zip, then edit. The copy carries skill files only, not the plugin's MCP setup. Skills in your private GitHub repo install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Microsoft.

Similar skills

Questions

What is the Azure messaging skill?

azure-messaging is an Agent Skill in Microsoft's microsoft/azure-skills repo. It gives a coding agent a diagnosis workflow for Azure Event Hubs and Service Bus SDK problems, such as connection failures, authentication errors, AMQP link detaches, message lock lost errors and duplicate events.

How do I install the Azure messaging skill?

In Claude Code, run /plugin install azure@claude-plugins-official to get the Azure Skills Plugin with the Azure MCP Server. For skill files only, install azure-messaging together with azure-diagnostics, because the language-specific troubleshooting guides it relies on live in the azure-diagnostics folder.

Why do I get MessageLockLost before the lock expires?

Microsoft's Service Bus troubleshooting guide says a lock can be lost when the AMQP link detaches, from a transient network failure, an outage or the service's 10-minute idle timeout, even if the lock time has not passed. The skill's guides cover this case and lock renewal, such as AutoLockRenewer in Python.

Which languages does the Azure messaging skill cover?

Its guides cover Python, Java, JavaScript and .NET for both Event Hubs and Service Bus, eight guides in all. Each names the current SDK package, such as azure-servicebus for Python or Azure.Messaging.ServiceBus for .NET, and lists common errors and known issues; the Python, Java and JavaScript guides also show how to enable logging.

Does the Azure messaging skill create queues or send messages?

No. It is a troubleshooting skill. Its MCP tools list namespaces, hubs, queues, topics and subscriptions, query diagnostic logs and check resource health. Fixes come as recommendations and code changes in your app, not changes to your Azure resources.

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.