Fix Dynamics 365 Mixed Reality Guides: Setup & Errors
Why This Is Happening
I've watched frontline workers stand in the middle of a factory floor, HoloLens on their head, staring at a blank screen where their Dynamics 365 Mixed Reality Guides should be loading. The guide author spent three days placing holographic instruction cards in exactly the right spots, and now the app either can't find the anchor, throws a vague sign-in error, or crashes silently before the first step even loads. I know how demoralizing that is , especially when management is watching a pilot deployment and expecting a smooth demo.
Dynamics 365 Guides is Microsoft's mixed-reality application built specifically for HoloLens. The premise is genuinely powerful: step-by-step holographic instructions that float right where the physical work is happening, visible exactly when a technician needs them, with no manual to flip through and no tablet to hold. But the platform sits at the intersection of four different technical domains, cloud identity, HoloLens hardware, a Windows PC authoring environment, and (often) Dynamics 365 Field Service or Supply Chain Management, and problems in any one of those domains can bring the whole thing down.
The most common failure points I've seen across enterprise deployments break into a few clear buckets. First, licensing and user role misconfiguration: if the person signing into the HoloLens app hasn't been assigned the correct Dynamics 365 Guides role in your environment, the app will authenticate but show nothing. Second, guide anchoring failures: spatial anchors in HoloLens rely on environmental scanning, and if the physical space changes, lighting shifts, or the HoloLens hasn't been properly calibrated, the anchor simply won't lock. Third, 3D object import problems: custom 3D assets need to meet specific format and polygon-count requirements, and the error messages when they don't are… not exactly illuminating. Fourth, Teams collaboration call issues: the integration between HoloLens Guides and Microsoft Teams has its own set of permissions and network requirements that many IT teams don't configure correctly up front.
One thing worth calling out right now: as of the time this guide was written, Microsoft has announced that Dynamics 365 Guides and Remote Assist will no longer be available after December 31, 2026. If you're mid-deployment or evaluating the platform, you need to factor that into your planning timeline. I'll cover what that means for your current implementation in the Advanced section.
The good news is that the vast majority of Dynamics 365 Mixed Reality Guides problems, even ones that look catastrophic on the surface, come down to a handful of fixable root causes. Let's work through them. Browse all Microsoft fix guides →
The Quick Fix, Try This First
Before you go deep on troubleshooting, there's one check that resolves roughly 60% of the Dynamics 365 Mixed Reality Guides problems I see in the field: verify that the HoloLens user has been assigned the correct role in your Dynamics 365 environment, and then force a fresh sign-out and sign-in on the device.
Here's exactly what to do. On your PC, open a browser and navigate to your Dynamics 365 environment URL (something like https://yourorg.crm.dynamics.com). Go to Settings > Security > Users. Find the account that's being used on the HoloLens. Click the user, then click Manage Roles. Confirm that either the Dynamics 365 Guides Author or Dynamics 365 Guides Operator role is checked, depending on whether this person is creating guides or following them. If neither role is assigned, that's your problem right there. Assign the appropriate role and save.
Now on the HoloLens: open the Start menu (bloom gesture or Windows button), go to Settings > Accounts > Sign-in options, sign out of the current Microsoft account, then sign back in. Once you're signed in, open the Dynamics 365 Guides app. Select your environment URL from the list. You should now see the guide library populate.
If you're running a domain-joined HoloLens in an enterprise environment, also confirm that the device's time is synchronized correctly, Kerberos authentication failures that look like Dynamics 365 Guides sign-in errors are often just a clock skew of more than five minutes. Check Settings > Time & Language > Date & time and ensure Set time automatically is toggled on.
This single role-assignment check has saved me hours on-site more times than I can count. Try it first before touching anything else.
The Dynamics 365 Guides PC authoring app is where guide creation starts. If the PC app isn't installed correctly or can't connect to your Dynamics 365 environment, you can't create or edit guides at all, and that blocks your entire workflow before you even get to HoloLens.
Download the Dynamics 365 Guides PC app from the Microsoft Store or from your Dynamics 365 admin portal. Before you install, make sure the PC meets the requirements: Windows 10 version 1903 or later, at minimum 8GB RAM (I'd recommend 16GB if you're working with heavy 3D assets), and a stable internet connection. The app needs to call back to your Dynamics 365 tenant on port 443.
After installation, launch the app and sign in with your Microsoft work account, the same one that has the Guides Author role assigned. At the environment selection screen, you'll type in your Dynamics 365 environment URL. A common mistake here is entering the full CRM URL with the path (like /main.aspx) instead of just the base URL. Use only https://yourorg.crm.dynamics.com with no trailing path.
If you see the error "We can't connect to your Dynamics 365 environment," open PowerShell and run:
Test-NetConnection -ComputerName yourorg.crm.dynamics.com -Port 443If TcpTestSucceeded comes back False, the issue is network or firewall, your IT team needs to whitelist Microsoft's Dynamics 365 IP ranges. If it comes back True and you still can't connect, the problem is authentication. Double-check the user role assignment from Step 0 above.
When the app connects successfully, you'll see the Guides home screen with a + New guide button and any existing guides listed below it. That's your green light to proceed.
HoloLens calibration is one of those things that gets skipped during rushed deployments and then causes mysterious problems for weeks afterward. I've seen guides where all the holographic instruction cards were consistently offset by about six inches, every single operator was reaching for the wrong bolt on an assembly. The root cause was always the same: eye calibration wasn't done for that specific user.
HoloLens 2 stores individual eye calibration profiles. Each person who uses the device should run their own calibration. Here's how to do it: put on the HoloLens, go to Settings > System > Calibration, and select Run eye calibration. Follow the prompts, you'll track a target dot with your eyes through a series of positions. The whole thing takes about 30 seconds. After calibration, run the Dynamics 365 Guides app and check whether your holographic objects align correctly with real-world markers.
If you're using the device in a multi-user environment where different operators share one HoloLens, each operator needs their own Windows account on the device so that HoloLens can store their individual calibration profile. Shared-device mode with a single account means every operator uses the same calibration, which is rarely accurate for everyone.
For the authoring workflow specifically, after launching the Dynamics 365 Guides app on HoloLens you'll be prompted to calibrate the HoloLens before placing holograms. The app displays alignment markers, small circles or lines, that you need to match up with corresponding physical markers in your real workspace. This calibration process is what lets the app know exactly where your guide's anchor point is in physical space. If the physical markers aren't clearly visible, clean them (dust and low contrast kill detection), and make sure the area has consistent, even lighting. Shadows and glare both degrade marker tracking.
When calibration succeeds, holographic objects will snap into place and remain stable as you move your head. If they're drifting or floating, repeat the calibration process.
Guide anchoring is the mechanism that ties your holographic content to a specific real-world location. It's the most technically interesting part of the Dynamics 365 Guides authoring workflow, and, predictably, one of the most common sources of operator complaints.
In the PC authoring app, when you create a new guide, the first major task is selecting an anchor type. You have three options: QR code anchor, circular code anchor, and holographic anchor. QR code anchors are the most reliable for industrial settings, the HoloLens scans the physical QR code printed on or near the equipment, and that becomes the fixed reference point for all holographic content in the guide. Print the QR code at a minimum of 101mm x 101mm for reliable scanning. Smaller than that and the detection fails intermittently.
Circular code anchors work similarly but use proprietary marker images included in the Guides documentation, download those from your Dynamics 365 Guides admin portal under the Anchor resources section. Holographic anchors use spatial mapping, which is flexible but drifts more in environments where the physical surroundings change (things get moved around, lighting changes significantly).
If operators report that their guides are appearing in the wrong location, shifted, rotated, or completely missing, the fix depends on the anchor type. For QR code and circular code anchors, check these things in order:
- Is the printed marker flat, clean, and undamaged? A creased or partially obscured QR code won't scan reliably.
- Is the marker within the HoloLens field of view at the start of the guide? Operators need to be standing within roughly 1.5 meters of the marker when they first open the guide.
- Has the marker been moved since the guide was authored? If someone shifted the QR code even slightly, re-anchor the guide in the PC app to match the new marker position.
For holographic anchors in frequently rearranged environments, switch to QR code anchors. The extra printing step is worth it.
Dynamics 365 Guides includes a default library of 3D holographic objects you can drop into guides without any conversion work, arrows, hand icons, warning symbols, numbered markers, and more. But a lot of enterprise teams want to import their own 3D models: CAD files from their equipment, custom part diagrams, or training animations. That's where things get complicated fast.
The supported import formats for Dynamics 365 Guides are GLB and GLTF for static 3D objects, and FBX for animated objects. The app does not natively import STL, OBJ, or proprietary CAD formats (STEP, IGES, SolidWorks files). If your engineers are exporting directly from CAD software, they need to convert to one of the supported formats first. Blender (free) handles this conversion well, export as GLB with the geometry triangulated.
Even after converting to GLB, you may hit polygon limits. The Dynamics 365 Guides documentation recommends keeping individual 3D objects under 65,000 polygons for smooth HoloLens rendering. I've seen objects with 400,000+ polygons imported successfully on the PC app only to crash the HoloLens app when that step is reached in the guide. Use a tool like Blender's Decimate modifier or Microsoft's open-source 3D Model Optimizer to reduce polygon count before import.
To import a 3D object, in the PC authoring app go to your guide, navigate to the step where you want the object, and in the right panel click 3D parts > Upload 3D object. Select your GLB file. If the upload spinner runs indefinitely and never completes, check your file size, keep individual GLB files under 128MB. Also check your browser's network console if you're on a slow connection; the upload times out after about two minutes of no response from the server.
After upload, the object appears in your guide's 3D library. In the HoloLens authoring mode, you can pick it up and place it in 3D space by airtapping and dragging. If the object appears as a pink box or a question mark placeholder in HoloLens, the file format wasn't converted correctly, re-export from Blender with Apply Transforms checked and try again.
One of the most valuable features in Dynamics 365 Mixed Reality Guides is the ability for a HoloLens operator to call a remote expert through Microsoft Teams, right from within the guide, at the specific step where they need help. The remote expert sees the operator's first-person HoloLens view, including the holographic guide content, and can draw annotations directly into the HoloLens field of view. In theory, it's incredible. In practice, I've seen this feature broken in more enterprise deployments than I've seen it working correctly on first try.
The Dynamics 365 Guides Teams integration requires that the HoloLens user account has a valid Microsoft Teams license assigned in Microsoft 365 admin center. Navigate to admin.microsoft.com > Users > Active users, find the HoloLens account, click on it, go to the Licenses and apps tab, and confirm that Microsoft Teams is checked under the assigned license. If Teams isn't licensed, the call button in the Guides app will appear but fail silently when tapped.
Network requirements for the Teams call from HoloLens follow the same requirements as any other Teams call, but HoloLens sits outside most corporate MDM network profiles. Make sure these ports are open from the HoloLens device's network segment:
TCP/UDP 3478, 3479, 3480, 3481 (Teams media relay)
TCP 443 (Teams signaling)
UDP 50000-59999 (Teams peer-to-peer media)If calls connect but the video is black or frozen, the issue is typically the firewall blocking UDP media relay. Work with your network team to allow UDP 3478–3481 from HoloLens outbound.
When a call works correctly, the remote expert on Teams desktop or mobile sees the HoloLens camera feed including any holographic overlay. They can annotate by drawing in their Teams interface and those annotations appear as holographic marks in the operator's view. If annotations aren't appearing on the HoloLens, confirm both the Teams desktop app and the HoloLens Guides app are on their latest versions, annotation rendering requires a matching API version on both sides.
Advanced Troubleshooting for Dynamics 365 Mixed Reality Guides
Once you've worked through the basics, some Dynamics 365 Mixed Reality Guides problems require digging into the enterprise layer, user role administration, Group Policy behavior, Event Viewer logs on the PC app, and integration-level configuration with Field Service or Supply Chain Management.
Diagnosing Role Assignment Failures with Event Viewer
If users report that they can sign into the Guides app but can't see any guides or get an "access denied" type error, look at the PC authoring app logs first. On the authoring PC, open Event Viewer (Win + R, type eventvwr.msc). Navigate to Applications and Services Logs > Microsoft > Dynamics > Guides. Look for Event ID 5000 (authentication errors) or Event ID 5100 (environment connection failures). The detail text in these events is far more useful than what the app UI shows you.
Fixing Dynamics 365 Field Service Integration Issues
The Dynamics 365 Field Service integration allows Field Service tasks to have guides attached to them directly, so a field technician gets their work order and the relevant Guides step-by-step instructions surface automatically. If guides aren't appearing in Field Service tasks, the most common cause is that the Field Service environment and the Guides environment aren't pointing to the same Dynamics 365 organization. Check under Field Service > Settings > Guides Integration and verify the environment URL matches exactly. A second common cause: the Field Service mobile app version is out of date. Guides attachment visibility requires Field Service mobile app version 8.8.x or later.
Supply Chain Management Integration
For manufacturing environments using the Dynamics 365 Supply Chain Management integration, guides can be attached to production processes, assembly line workers see holographic instructions that align with their production order. If guides aren't triggering from Supply Chain Management production orders, verify that the Mixed Reality Guides feature flag is enabled in Supply Chain Management under Feature Management. Also confirm that the Supply Chain Management environment has the Guides connector installed and configured with a valid service principal that has read access to the Guides environment.
GxP-Regulated Industry Configurations
For pharmaceutical, biotech, and other GxP-regulated environments, Dynamics 365 Guides has specific compliance configuration options. Guide versioning and completion audit trails are available through the Guides Analytics features. Make sure your environment has the audit log feature enabled in Dynamics 365 admin settings, and that the Guides Power BI template is deployed to give compliance teams visibility into guide completion rates, time-per-step, and operator actions, all of which can be part of a validation protocol in a regulated industry.
US Government Environments
If you're deploying Dynamics 365 Guides in a US Government (GCC or GCC High) tenant, note that the app endpoints are different from commercial tenants. The PC app must be configured to point to the government environment URL (typically ending in .crm9.dynamics.com for GCC). The standard commercial endpoints will not work and will return authentication errors that look identical to role assignment problems.
Prevention & Best Practices for Dynamics 365 Mixed Reality Guides
The deployments I've seen go smoothly share a common pattern: the IT and operations teams did about two weeks of structured preparation before any HoloLens went on a worker's head. The ones that struggled skipped that preparation and spent months firefighting avoidable problems.
Start with a proper pilot environment. Set up a Dynamics 365 sandbox environment specifically for Guides development and testing. Author your guides there, test them end to end on real HoloLens hardware in the actual physical location where they'll be used, and only promote to your production environment once the guide works reliably for five different users. The physical location matters, a guide that anchors perfectly in the training room often fails in the actual factory floor because the surfaces and lighting are different.
Manage your 3D asset pipeline early. If your organization plans to import custom 3D models, establish a conversion workflow before authors start building guides. Designate one person or team responsible for converting CAD exports to optimized GLB files, don't let each guide author attempt this on their own. Inconsistent polygon counts and file formats are the single biggest source of HoloLens performance problems in organizations that use custom 3D content.
Plan for the end-of-support date. Microsoft has confirmed Dynamics 365 Guides reaches end of support on December 31, 2026. Any new guide authoring you do now should be designed with exportability in mind. Document your guide content in human-readable formats (Word or PDF) alongside the Guides platform so you have a fallback, and start evaluating what replaces Guides in your organization's mixed-reality training strategy after 2026.
Set up Guides Analytics from day one. The Power BI templates for Dynamics 365 Guides Analytics give you completion rates, time-per-step, and which steps operators are spending the most time on (or skipping). This data is gold for improving guide quality, but only if you start collecting it early. An analytics setup two months into your deployment means two months of missing baseline data.
- Print QR code anchors at 101mm minimum size and laminate them, anchor detection fails on wrinkled or low-contrast markers
- Assign the HoloLens Teams license in Microsoft 365 admin center before your first training session, not during it
- Run HoloLens eye calibration for every new user before their first guide session, 30 seconds of calibration prevents hours of "the holograms are in the wrong place" complaints
- Keep individual 3D GLB files under 65,000 polygons and under 128MB to avoid HoloLens rendering crashes and upload timeouts
Frequently Asked Questions
Do I need programming or 3D modeling experience to create a Dynamics 365 Guides guide?
No, and this is genuinely one of the platform's best features. The PC authoring app is built so that subject-matter experts (maintenance technicians, quality engineers, training coordinators) can create guides without any coding or 3D design background. You create step-by-step instruction cards with text, images, and video on the PC app, then put on the HoloLens to physically place those cards in 3D space next to the real equipment. Microsoft includes a default library of 3D holographic objects, arrows, numbered markers, warning icons, so you don't need to import any custom models to get started. Custom 3D imports add complexity, but they're optional.
My Dynamics 365 Guides app keeps crashing on HoloLens, what should I check first?
The most common cause of HoloLens Guides crashes is a 3D object in the guide that exceeds the polygon limit or has a corrupted GLB file. Open the guide in the PC authoring app and temporarily remove all custom 3D objects from the crashing step, then test again on HoloLens. If the guide runs without crashing, add the 3D objects back one at a time to identify which file is the problem. Then re-export that file with a lower polygon count (target under 65,000 polygons using a mesh decimation tool). If the guide crashes even without custom 3D content, update the HoloLens OS and the Guides app to the latest versions, Microsoft regularly releases stability fixes.
How do I attach a Dynamics 365 Guide to a Field Service work order?
First, confirm the Guides integration is enabled in your Field Service environment: go to Field Service > Settings > Guides Integration and make sure the toggle is on and the Guides environment URL is entered correctly. Once that's configured, open any work order in Field Service, find the Related tab, and you'll see a Guides section where you can search for and attach existing guides by name. The guide then appears automatically in the Field Service mobile app when a technician opens that work order, they tap the guide link and it launches directly in the Dynamics 365 Guides HoloLens app. Both the Field Service and Guides environments need to be on the same Dynamics 365 tenant for this to work.
Can multiple people collaborate on the same guide at the same time?
Not simultaneously in the same editing session, Dynamics 365 Guides is a single-author-at-a-time system on the PC app. If two people try to edit the same guide at the same time, the second person to save will overwrite the first person's changes. The Teams integration, however, does support real-time collaboration during guide operation: an operator on HoloLens can call a remote expert through Teams, share their view, and receive live annotations, all while following the guide steps. For authoring coordination across teams, Microsoft recommends using Guides folders and clear ownership of individual guide files, similar to how you'd manage shared documents in SharePoint.
What happens to our Dynamics 365 Guides after the December 2026 end-of-support date?
After December 31, 2026, Microsoft will no longer provide updates, bug fixes, or support for Dynamics 365 Guides and Remote Assist. The app won't suddenly stop working on that date, but it will stop receiving security patches and may become incompatible with future HoloLens OS or Microsoft 365 updates over time. If your organization has active guide content, start planning your migration strategy now. Export and document your guide content in alternative formats, and watch Microsoft's announcements for any successor mixed-reality tooling. Organizations with Unified Support contracts should open a conversation with their Microsoft account team about transition planning well before the deadline.
My guide anchor worked fine last week but now the holograms appear in completely the wrong place, what changed?
The most likely culprit is that something in the physical environment near your anchor marker changed. QR code and circular code anchors depend on the marker being in the same physical position it was when the guide was authored, if the marker was moved even a few centimeters, or if something large near it shifted (equipment, shelving), the spatial mapping can drift. Check that the printed anchor marker is exactly where it was during authoring and hasn't been obscured, damaged, or repositioned. Also check environmental lighting, dramatic lighting changes (especially going from artificial light to direct sunlight or vice versa) can interfere with marker detection. If the marker position genuinely changed, re-anchor the guide in the PC authoring app and publish the update.