When you create a new Microsoft Teams tenant and configure an app setup policy to pin an app, the app may not appear in the left rail. This happens even though the policy shows the correct assignment. The root cause is usually a delay in policy propagation or a mismatch between the policy assignment and the user's effective policy. This article explains why the pin fails and provides a step-by-step fix to get the app pinned consistently.
You will learn how to verify policy assignments, force a refresh, and confirm that the app is available for your tenant. The steps work for both Teams desktop and web clients.
Key Takeaways: Pin Apps Reliably with Teams App Setup Policy
- Teams admin center > Teams apps > Setup policies: Shows the exact policy applied to a user and whether the pinned app is present.
- Teams admin center > Users > Manage users > Policies: Displays the effective app setup policy for a specific user.
- Ctrl+F5 in Teams desktop: Forces a client refresh to pick up the latest policy changes without restarting.
Why Teams App Setup Policy Does Not Pin an App in a New Tenant
The app setup policy controls which apps appear in the Teams left rail for users. When you assign a policy, Teams must replicate the change to all front-end servers. In a new tenant, this replication can take up to 24 hours, but it usually completes within a few minutes. If the pin does not appear, the most common cause is that the policy assignment is not yet effective for the user.
Another frequent cause is that the app itself is not available in your tenant. If the app is blocked by an app permission policy or is not installed, the setup policy cannot pin it. Teams hides any app that is not allowed, regardless of the pin setting.
A third cause is that the user is not assigned to the policy you edited. New tenants often have a single default policy, but if you created a custom policy and assigned it to a user, the assignment must be correct. You can verify this in the Teams admin center.
Steps to Verify and Fix App Setup Policy Pinning
Follow these steps in order. Each step confirms or corrects a possible cause.
- Check the app permission policy
Go to Teams admin center > Teams apps > Permission policies. Select the policy assigned to the user and confirm that the app is set to Allowed. If the app is blocked, change it to Allowed and save. Then wait 10 minutes. - Verify the app is installed in the tenant
Go to Teams admin center > Teams apps > Manage apps. Search for the app name. If the status is Not allowed, select it and choose Allow. If the app is not listed, you must add it from the Teams app store or upload a custom app. - Confirm the user's effective app setup policy
Go to Teams admin center > Users > Manage users. Select the affected user, then choose Policies. Look at the App setup policy field. It must show the policy that contains the pin. If it shows Global (Org-wide default), assign the correct policy to the user. - Edit the app setup policy to add the pin
Go to Teams admin center > Teams apps > Setup policies. Open the policy that applies to the user. Under Pinned apps, choose Add apps. Find the app, select Add, then choose Add again. Set the order if needed, then save. Wait 10 minutes. - Force a client refresh
In the Teams desktop client, press Ctrl+F5 to refresh the app. On the web client, close the tab and reopen Teams. If the pin still does not appear, sign out and sign back in. - Restart Teams completely
Close Teams from the system tray by right-clicking the icon and choosing Quit. Wait 10 seconds, then reopen Teams. This clears the local cache and forces a fresh policy download.
If Teams Still Does Not Pin the App
Some issues persist even after the main steps. Here are the most common ones and their fixes.
Teams Shows the Pin Only After 24 Hours
In a brand-new tenant, policy replication can take up to 24 hours. If you have waited less than that, the pin may appear later. To speed up the process, you can force a full sync by running the following PowerShell command in the Teams module: Connect-MicrosoftTeams then Get-CsTeamsAppSetupPolicy -Identity "Global". This does not force replication but confirms the policy exists.
The App Is Pinned but Disabled for the User
If the app appears grayed out in the left rail, the user may not have permission to use the app. Check the user's app permission policy again. Also, some apps require a license or admin consent. Verify that the app is not blocked by an Entra ID conditional access policy.
The Pin Works on the Web Client but Not on Desktop
The desktop client uses a local cache. Clear the cache by closing Teams, deleting the folder %appdata%\Microsoft\Teams, and reopening Teams. This removes all cached policies and forces a fresh download.
Multiple Policies Conflict
If a user is a member of a group that has a policy assignment, that group policy overrides the user's direct assignment. Check the user's effective policy in the admin center. If a group policy is applied, edit that group policy instead.
App Setup Policy: Global vs Custom Policy
| Item | Global (Org-wide default) | Custom Policy |
|---|---|---|
| Applies to | All users without a specific assignment | Only assigned users or groups |
| Default pin set | Teams, Activity, Chat, Calendar | Defined by admin |
| Editing impact | Affects entire tenant | Affects only assigned users |
| Replication time | Up to 24 hours | Up to 24 hours |
| Best practice | Use for baseline settings | Use for specific departments or roles |
Conclusion
You can now pin apps in a new tenant by verifying the app permission policy, the app availability, and the user's effective setup policy. Always wait 10 minutes after a policy change before testing. Use Ctrl+F5 to refresh the client without a full restart. If the pin still fails, check group policy assignments and clear the Teams cache. For advanced scenarios, use PowerShell with the Teams module to inspect the exact policy settings.