PROMOTION_NOT_WORKING on Mac Display, what causes it and how to fix

By Sai Kiran Pandrala · Last verified: 2026-05-31 · Source: Apple Support docs, Apple Communities (discussions.apple.com), community Q&A

When PROMOTION_NOT_WORKING on Mac Display, what causes it and how to fix bites you on Mac Display and External Monitors, the first instinct is to open a ticket. Most of the time you do not have to. The steps below are the ones Apple Support and Apple Business / Enterprise Support would walk you through on the call.

What promotion_not_working on mac display, what causes it and how to fix actually involves on Mac Display and External Monitors

The PROMOTION_NOT_WORKING error from AWS typically surfaces with the message "ProMotion 120Hz not engaging". The error code itself is what you grep for in AWS re:Post or in AWS Support cases, not the human-readable line.

On Mac Display, this most often comes from one of three causes: a missing or restrictive IAM permission, a service-level limit you have hit, or a transient AWS-side capacity issue. The fix path differs by which.

The rest of this page is the structured fix path. Start with diagnose, then remediation, then the automation options so you do not have to do this by hand the next time it surfaces. Verify and safety sections at the end are the discipline that keeps the fix from regressing in production.

Diagnose first, fix second

Look at the Jamf Pro change management entry or Apple Business Manager audit event for the failed call, even if you are not enrolled in macOS unified logging and iOS sysdiagnose Log Router. The basic 90-day event history works for most diagnostic purposes and lives in the console under Jamf Pro change management log and Apple Business Manager audit log > Event history. Filter by event name (the API action) and time range; the event JSON shows the exact user identity, source IP, request parameters, and error code.

Reproduce the failure with the Terminal commands (defaults, plistbuddy, killall, sudo, system_profiler) and Apple Configurator 2 / Jamf APIs / MDM commands in --debug mode. The full SigV4 request payload it emits, plus the exact endpoint URL it resolved to, is what Apple Support and Apple Business / Enterprise Support uses to verify policy, region, or parameter issues without you having to share IAM credentials. Save the debug output to a file with ... --debug 2> debug.log and you can search it for the failed aws.request entry.

Diff against last known good. The last config change you made is the cause about three quarters of the time, even when the change should not have mattered. Use Jamf inventory history and Time Machine snapshots (or your Terraform / Deployment Manager or Terraform drift report) to see the actual delta between the resource state when it worked and when it broke. The change you remember is often not the only change that happened.

Solution-focused remediation path

If you cannot reproduce the failure consistently, the cause is probably a race condition or a session-cache issue. Run the call with --profile set to a fresh STS session, in a different region you control, with a single concurrent request. If it works there but fails in your normal setup, the difference is the bug.

Most Mac Display and External Monitors failures fall into one of three buckets: IAM permission gap, networking path break (security group, NACL, or VPC endpoint policy), or service-limit / quota hit. Run that mental triage first - it covers around 80 percent of real-world cases. If the failure does not fit any of the three, it is likely a service-side regression worth opening a re:Post or support ticket for.

When the failure happens in production but not in dev, do not just compare the IAM policy. Compare the Org Policy / RCP at the OU level, the permission boundary on the role, and the resource-based policy on the target. One of those is almost always different between accounts. Policy Intelligence recommendations bundles make this comparison routine.

Automate this fix so you do not do it twice

Automate the fix in Terminal with defaults, plistbuddy, and system_profiler

On macOS, the most reliable repair primitives are the built-in Terminal tools. defaults read reveals the current preference state, defaults write changes it, and killall cfprefsd forces the preferences daemon to flush so the new value actually takes effect. /usr/libexec/PlistBuddy handles structured plist edits when defaults is not enough. For hardware and inventory checks, system_profiler with the right datatype is the canonical read; for example SPHardwareDataType, SPNetworkDataType, or SPInstallHistoryDataType.

# Template - replace with your actual key path
defaults read com.apple.mac 2>/dev/null | head
sudo killall cfprefsd
/usr/libexec/PlistBuddy -c 'Print' ~/Library/Preferences/com.apple.mac.plist
system_profiler SPHardwareDataType -json | head -40

Add a Smart Group + webhook so you catch the next occurrence

The cheapest way to never see the same incident twice is a Jamf Pro Smart Group that watches for the symptom (specific extension attribute value, specific OS version, specific app build) and fires a webhook into Slack, PagerDuty, or a Jamf-API-driven Lambda when the count drifts above your normal baseline. For Mac Display and External Monitors, the relevant extension attributes live under script-evaluated checks - defaults read outputs, system_profiler values, or a log show grep against macOS unified logging. Set thresholds against observed normal, not against round numbers.

Build a Self Service item with manual approval for risky fixes

For multi-step fixes that include a destructive action (Reset NVRAM, delete keychain, erase user data), publish the fix as a Self Service item in Jamf Pro or Kandji. The user clicks one button, the script runs, a notification confirms success. Couple it with a Jamf Pro approval workflow if your security model requires a second-person sign-off before any destructive step runs. The audit trail lives in the MDM change log with the requester and approver identity attached.

Common pitfalls and what to watch for

The most common pitfall when fixing this on Mac Display and External Monitors is treating it as a one-off rather than as a recurring class of incident. The same misconfiguration tends to happen again after a deployment, a role rotation, or a region migration unless the fix is codified. Add a Apple Configuration Profile restriction payload, Organization Policy condition, or Apple Configuration Profile or MDM restriction payload that prevents the same misconfig from being introduced again. Documentation alone does not survive turnover.

Another common trap: confirming the fix on a single resource and assuming the fleet is healthy. Loop your check across every account, region, and IAM principal that could exhibit the same symptom. If you cannot enumerate the affected scope without a script, you do not yet understand the scope.

Verify the fix worked

• Watch for 24 to 48 hours. Activity Monitor + macOS unified logging + Jamf inventory reports can mask issues with cached health for 6 to 12 hours, especially Cloud CDN and Cloud DNS.
• Capture the new state in a runbook so the next person on call does not have to rediscover this. Push it to Confluence or your team wiki, not into Slack.

Safety, rollback, blast radius

• Test in a non-production account if your environment has Resource Manager and Organization Policy or Cloud Resource Manager (organizations, folders, projects). The cost of one sandbox account is cheaper than one rollback meeting.
• Export the existing config before changing it. Most Mac Display and External Monitors resources support describe + export to JSON via CLI - capture that to source control before you start.
• Maintenance window discipline: if the change touches DNS, certificate rotation, or anything that emits TLS handshakes, line up a window with stakeholder notification, not a heroic mid-day swap.

FAQ

Related fixes

Related guides worth a look while you sort this one out:

• STUDIO_DISPLAY_CAM_RECALL on Mac Camera. what causes it and how to fix
• DISPLAY_WAKE_FAIL on Mac Display, what causes it and how to fix
• EXT_DISPLAY_NOT_DETECTED on Mac Display, what causes it and how to fix
• EXT_LOW_RES on Mac Display: what causes it and how to fix
• FLICKER_DISPLAY on Mac Display, what causes it and how to fix
• CAL_ALARM_NOT_FIRING on Calendar Mac, what causes it and how to fix