Missing entitlement for API HomeKit error

During a test run of my HomeKit application in Xcode, after some time the app did run smoothly, I've started for one characteristic to get a pretty weird error in the readValueWithCompletionHandler: callback block:

Let me start with the messages here:

"Handler does not support background access"
...
"Missing entitlement for API."

That error and the entitlement it references are a leftover artifact from the Apple Watch's initial release, not a "real" entitlement we actually grant/use. Very early in watchOS 2.0’s development, an entitlement WAS created and integrated into the framework so that watchOS extensions (which run "in the background") running on the iPhone could control HomeKit. However, very early in the pre-release development testing process, it became clear that there were so many other "foreground only" edge cases that it was better to simply "lie" to the extension (so our frameworks considered it "foreground") instead of trying to sort out all of those edge cases.

That made the HomeKit entitlement unnecessary, but there wasn't any reason to remove the existing code, so it was left in place, referencing an entitlement that we've never granted to any developer and probably never will.

That leads back to the error itself. Is our app in the background when it happens? If so, then the answer is "don't do that". HomeKit background access isn't supported [1].

Note please that immediately after launch (and for some time after that) the value was read in through the same code without any problem.

SO, there are three cases here:

1. If you're in the foreground, the API works fine.

2. Immediately after an app enters the background, the system continues to treat it as "foreground" for "awhile.” That might seem strange, but the problem here is that an API like Metal isn't something an app can just "stop" using. Preventing an app from freeing up Metal resources because it's "in the background" is counterproductive, so the system continues treating the app as "foreground" despite the fact it’s in the background.

3. If you're running in the debugger, the system’s behavior can get "weird.” The debugger disables normal app suspensions as well as other things like the main thread watchdog, but that can create unexpected side effects in other places. For example, many daemon's rely on process assertion expiration to trigger behaviors you're normally associated with "entering the background,” but expiration only occurs if/when your app is actually eligible to suspend, so they don't fire. Further complicating things, most of those cases aren't even bugs, as things like the "audio" background category rely on them.

Strangely enough, when I've switched the device through the Home application,

The background restriction is tied to your ability to send commands "into" HomeKit, NOT HomeKit's ability to interact with your app. Things like notifications that you've set up before entering the background may continue to work, particularly if you're dealing with #3.

[1] Why that is the case is a question I'm happy to answer if you're curious, but it's almost dinner time and I should finish up.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Thanks a lot, interesting!

I do apologise for stupidity: I've completely forgot there is the foreground-only limitation. Sigh.

As for [1] (I hope you enjoyed the dinner :), and), correct me please if I am wrong, but I believe it is so for privacy concerns, so that no 3rd party app can analyse what I do with my accessories for evil goals.

Nevertheless this is an application I wrote myself to be run by myself for my own completely benign (and even if not, it's my problem) goals in my own home (still the same one of https://developer.apple.com/forums/thread/849339), thus of course I don't mind it analyses my behaviours (it is its very purpose in fact). Compare please also closely related comment https://developer.apple.com/forums/thread/849288?answerId=907772022#907772022. I've added a request for the background support to my feedback ticket FB25066661.

If you can see any way to overcome these limits (both the background and the ones caused by the profile, detailed in the thread linked above) in this particular case (my own private app run in my own home only), I'd be grateful for any advice.

As for [1] (I hope you enjoyed the dinner :)

I did actually!

and), correct me please if I am wrong, but I believe it is so for privacy concerns, so that no 3rd party app can analyse what I do with my accessories for evil goals.

Actually, no, not at all. The actual reason is to try to minimize/reduce the likelihood that you'll end up with a house where crazy things happen that you can't understand, explain, or debug.

The issue here is that, from the beginning, HomeKit's been built around the idea that your home's configuration isn't something that’s tied to any particular device or "setup". You don't have a home server that you manage and configure; you have home configuration that’s visible and editable on all of your devices, and things "just work". In its original design, the idea was that the home database was simply shared to all of your devices, any one of which could individually connect to an accessory and control it.

Every device had access to the full home state and could independently manage "everything". This had all sorts of effects on HomeKit's design. For example, notice that basic automation only allows you to change an accessory to a specific state and can only be scheduled down to ~1 min. That combination means that if multiple controllers happen to execute exactly the same automation, nothing "bad" actually happens— whichever command arrives "second" is ignored by the accessory (since it's already changed state) and the relatively large timing window means that the devices don't really need to be synced to the same time.

In practice, that did have issues (particularly as the number of controllers in the home increased), which eventually led to the introduction of "Home Hubs", which simplified things by letting us route all commands through one controller. That centralization also opened up other opportunities, most notably embedding shortcuts in automations. Multiple controllers running the same shortcut at the same time could cause huge problems, but the home hub architecture prevents that from happening by routing all commands through the same controller.

In any case, the key idea this is all built on is that ALL of your home’s configuration (including automations) is captured in a single data store, which is then shared among devices. Any device can modify the data store. One device (the Home Hub) may be responsible for executing the data store, but that role isn't particularly "special" or complicated. If the Home Hub goes offline, then we can pick another without anything really being visible to the user.

Now, switching to the user perspective, any time an accessory does something, there are only two reasons it can happen:

1. A user on a device directly "did something" in an app they were actually using.

2. It happened "on its own" as part of an automation they configured.

Similarly, if something "weird" happens, the investigation is straightforward— "ask your family" (#1) or open Home.app on any device you have at hand and start looking through your automations.

...and the words "any device" are why this:

I've added a request for the background support to my feedback ticket FB25066661.

...isn't going to happen. More specifically, allowing background HomeKit access means that investigating "mysterious" behavior could require systematically looking at EVERY device you own as you try to determine which of those devices originated the unexpected command. Even worse, once multiple apps are involved, the ultimate problem could be a side effect of the interactions between different apps on different devices owned by different users. Frankly, this worst case here is bad enough that I think it would make HomeKit effectively unusable.

Advanced users don't think about this because their perspective is that they want to set up some kind of "home management server" that does "interesting things," and they're frustrated by the extra friction the foreground requirement creates. The problem is that the "home management server" concept ONLY works when there is only one of them, and the friction the foreground requirement creates IS what's preventing more than one of them.

Shifting topics:

Nevertheless, this is an application I wrote myself to be run by myself for my own completely benign (and even if not, it's my problem) goals in my own home.

In terms of the code signing issues, the path forward here is to either pay for a developer membership or use the "nuclear option.” One other comment about the nuclear option, based on one of Quinn's notes:

IMPORTANT Do not disable SIP on a machine you care about. I do all of my EndpointSecurity testing in a VM, so I don’t have to disable SIP on my main work machine.

Using a VM as the "container" you run THIS particular app in isn't a terrible idea. You can restrict its network access to reduce exposure, and you can keep all of "your" data off that system to limit risk. If I were doing this myself, I think what I'd do is create a new iCloud user that was JUST for this machine, then share my home to that user to give it access. There are things you could do to harden it further, but the best protection is simply not caring about the contents of the machine.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Thanks again for all the detailed and very interesting insights!

Nevertheless I am afraid I do not quite get it. Seems to me (probably due to my misunderstanding) that none of these concerns should apply to my application, which never ever tries to set or change anything in HK.

All it does is reading the characteristic values; and even that just since waiting for the update notifications is unreliable, as detailed in https://developer.apple.com/forums/thread/849598.

Based on this and my (probably mistaken) understanding of what you wrote, there should be absolutely no reason not to allow my app to work seamlessly in the background. What do I miss here?

P.S. Just for the record, in future I shall need to change a couple of things, namely

• the setting of the thermostat which drives the main heating;
• switching a couple of power outlets which control some auxiliary heating units on/off.

At this moment though, it is a far future and not my pressing concern; that is the observing and analysing the current state, effectively, far as HK is concerned, read-only.

Based on this and my (probably mistaken) understanding of what you wrote, there should be absolutely no reason not to allow my app to work seamlessly in the background. What do I miss here?

The issue here isn't really about your app or use case, it's about the requirements of our larger platform and needs. We've never granted this entitlement to any developer and, for the reasons I explained above, thats not going to change.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

I do apologise I've expressed it seemingly not clearly enough.

What I can't understand is why the reasons explained above forbid read-only background applications which never ever change anything in HK, regardless the platform size and use case (given the privacy/analysis is of no concern).

What I can't understand is why the reasons explained above forbid read-only background applications which never ever change anything in HK,

The issue here is that, like most of our API, homed's background checks are primarily implemented during the initial connection and a few other critical bottlenecks within homed, not at the individual entry point for every single entry point into the framework. This requires both a lot less code to implement and reduces the possibility that a particular path will be missed. Note that this is one of the reasons you'll sometime see characteristic notifications arriving in the background- depending on the situation, notifications out don't necessarily "hit" any chokepoint, so the message gets posted to your app even though it's in the background.

SO, in theory, yes, we could allow read-only access, however, practically speaking it would require a lot more work than you'd think, as we'd need to strip out the existing enforcement system and then retrofit a new system, carefully auditing every single entry point to determine whether or not it should be allowed. Realistically, that's not going to happen, as it's a great deal of work to enable something that most apps can't really benefit from (since they're not running in the background anyway).

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Thanks, I see.

How then do I write my own private application, which is intended to run only on my own devices (namely on one of my Macs), which constantly observes and occasionally changes some HomeKit characteristics?

It needs to run for a long time (thus, there can't be the completely absurd good-for-just-a-few-days profile); it needs to run at background at the very least occasionally when I do some work on that particular Mac (the rest of the time it might be at foreground), and normally, that Mac won't be the one where the application has been built (for it's my 24/7 htpc mini, which does not contain Xcode at all).

Given the above, there's no potential problem with things like

crazy things happen that you can't understand, explain, or debug

for I have complete logs of what my app does, and should it begin to look crazy, I can easily disable it in no time flat.

Thanks!

It needs to run for a long time (thus, there can't be the completely absurd good-for-just-a-few-days profile); it needs to run at background at the very least occasionally when I do some work on that particular Mac (the rest of the time it might be at foreground),

OK, so one detail to understand is that macOS and iOS mean TOTALLY different things when they say "foreground" and "background". iOS implements a very complex system for constraining apps ability to execute code "in the background", basically NONE of which exists on macOS. macCatalyst does port some of that to macOS, however, macOS also provides a VERY large set of tools that allow you to manipulate/distort how the system handles your app.

I haven't experimented with how this plays out with HomeKit, but I suspect HomeKit on macOS considers your app "foreground" as long its running, regardless of background state. If that isn't the case, then I suspect that you could "trick" it into thinking you were with some experimentation.

However:

and normally, that Mac won't be the one where the application has been built (for it's my 24/7 htpc mini, which does not contain Xcode at all).

The suggestion I made to "use a VM" solves the issue as well, as you can configure the VM to run "headless", at which point your HomeKit app running in the VM WILL always be "foreground", even if you can't see it.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Thanks a lot!

I've tested it a bit, and preliminarily it seems that — at least in my current macOS 27.0.1 (26A434) — my Catalyst application is considered foreground, far as the UIApplicationWillResignActive/DidBecomeActive notifications say, whenever it is not hidden. Hidden seems to be about the one case when the app goes „background“, unhidden goes back „foreground“ immediately. Frankly, some surprise for me, for I was sort of used to interpret „foreground“ on a Mac as (essentially and roughly) “has the keyboard/focus“. This is quite different point of view, which alleviates the problem very considerably :)

As for the rest I deeply regret to say so far, I have absolutely no experience with VM. I shall find and study some documentation (or, perhaps, if you just happen to have a link to some good howto for Mac at hand, I'd appreciate if you could send it).

Thanks again very much; your help is really appreciated!

And again, one more question, hopefully you are not completely fed up as of now :)

Given the potential problems detailed in https://developer.apple.com/forums/thread/850391?answerId=909802022#909802022, I am reconsidering the behaviour of my home control. Originally I intended to make all the changes needed (essentially, setting thermostats and a couple of power plugs) directly from my application, sending my characteristics the writeValue:completionHandler: messages as needed.

Now, I am moving as much functionality as possible to automations.

This though leads to a completely new problem — debugging.

Far as the control was at my side, I could have easily kept and analysed detailed logs. Now, when the control is at the hub/automation side, I can't be really sure whether all works as intended, whether there's perhaps some subtle bug in the predicates set to the triggers etc. Is there a way to get to a detailed log of what and when and why a trigger (created by my application) did or did not?

All I have found for this so far is the lastFireDate property of HMTrigger. Which is far from optimal, but could help a bit; alas it is deprecated and does not work anyway. Is there anything better now? Thanks!

Another very weird problem happened today :(

Xcode built my (Catalyst, HomeKit) application all right, but refused to launch it reporting “LaunchServices has returned error -54”. It could not be launched from Finder either (“Finder does not have permission to open (null)”). Strangely enough, directly from Terminal (“...my.app/Contents/MacOS/myapp”) it did run without any complaint. Also, when re-signed using

codesign --remove-signature my.app
codesign --force --deep --sign - my.app

allowed it to be launched from Finder all right. A re-build in Xcode caused again “error -54”.

I've resorted to the well-know Windoze-fix, ie., restarting my device. That indeed did help, now I can launch the application from both Xcode and Finder without any dirty tricks...

... but I've found that UIDevice.currentDevice.identifierForVendor did change (I presume most probably this was the root of the launch problems, along with the darned profile), and all the HomeKit uniqueIdentifiers changed as well.

What the :( I naïvely thought these IDs never change for the same device and the same application bundle identifier — none of which changed. What did happen, and how to prevent this problem in future? Thanks!

Hm, to partially answer my own question, I've just found in the documentation of identifierForVendor

The value changes when the user deletes all of that vendor’s apps from the device ... The value can also change when installing test builds using Xcode or when installing an app on a device using ad-hoc distribution. Therefore, if your app stores the value of this property anywhere, you should gracefully handle situations where the identifier changes

That feels crazy. The device is still the same. The application is still the same (based on its bundle identifier). Why on earth ever to change something which should “uniquely identify a device to the app’s vendor”?!?

Well, anyway, this part is not that important; I've used the thing just in a naïve idea that it would, well, identify the device to me. Can live without that. The most important part is, how do I make sure that for the same application (same bundle id) on the same device all the HomeKit uniqueIdentifiers remain unchanged? Thanks.

(Considerably less important, but also interesting question is, what API could I use so that two applications, one Catalyst, another standard AppKit, would reliably get the same result on the same device — regardless “test builds”, “the user deletes all apps”, or whatever like that —, and different result on different devices?)

That feels crazy. The device is still the same. The application is still the same (based on its bundle identifier). Why on earth ever to change something which should “uniquely identify a device to the app’s vendor”?!?

User Privacy. More specifically, there WAS an API that uniquely identified a given device called, appropriately enough, "UIDevice.uniqueIdentifier". The same identifier was available to all device and, as I recall, the only time it ever changed was if the device was wiped.

The problem is that it ended up being widely abused for cross app tracking and other kinds of privacy abuse. UIDevice.identifierForVendor was specifically created to replace it with an API that better protected user privacy.

Well, anyway, this part is not that important; I've used the thing just in a naïve idea that it would, well, identify the device to me. Can live without that. The most important part is, how do I make sure that for the same application (same bundle id) on the same device all the HomeKit uniqueIdentifiers remain unchanged?

I suspect you can't, at least not when you do this:

Also, when re-signed using

I don't know what exactly changed about the signing between those to builds, but my guess is that the change was significant enough that the system determined that your app was a different app, which then caused all the identifiers to change.

(Considerably less important, but also interesting question is, what API could I use so that two applications, one Catalyst, another standard AppKit, would reliably get the same result on the same device — regardless “test builds”, “the user deletes all apps”, or whatever like that —, and different result on different devices?)

The typical approach is to use an app group or other fixed file system location to share data between the your apps. That data can then include whatever you need.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Thanks again very much for the detailed insight!

Frankly I must admit I can't see how my privacy could be compromised if any 3rd party application, evil as they come, happens to be able to distinguish and/or match my devices it just happens to run on; but then, it would be just a limitation of my imagination, nothing else (and not worth to pursue) :)

(Also, I sort of wonder how those HK non-unique-unique-IDs really help privacy. If the problem happens more often, I am sadly prepared to store/match the accessory and characteristic attributes, finding thus the same items with a very high reliability and create an appropriate uniqueIdentifier translation table. Since any evil application can do that just as well, seems to me the ever-changing IDs help privacy just a very little, if at all... But again, that's not worth pursuing; self-evidently I overlook something of importance...)

Thanks again!

Well, darn. Now it happened on another computer. I did absolutely nothing suspicious, just slightly improved the code (without changing the bundle ID of course!), ⌘r, build succeeded, and ... “Could not launch “HomeObserverNA””. The complete report is below :( An attempt to launch the built application from Finder says “The application “Finder” does not have permission to open “(null)”.“. Quadruple sigh.

I wonder whether there is a way to fix the problem (a) without restarting my Mac (which at this moment would be very inconvenient), (b) without changing all the uniqueIds... Can anybody see a cure? Of course this time I am not about to use codesign in any way.

===

Could not launch “HomeObserverNA”
Domain: IDELaunchErrorDomain
Code: 20
Recovery Suggestion: LaunchServices has returned error -54. Please check the system logs for the underlying cause of the error.
User Info: {
    DVTErrorCreationDateKey = "2026-10-27 17:57:55 +0000";
    DVTRadarComponentKey = 113722;
    IDERunOperationFailingWorker = IDELaunchServicesLauncher;
}
--
The operation couldn’t be completed. (OSStatus error -54.)
Domain: NSOSStatusErrorDomain
Code: -54
User Info: {
    "_LSErrorMessage" = permErr;
    "_LSFile" = "LSOpenCore.mm";
    "_LSFunction" = "_LSOpenStuffCallLocal";
    "_LSLine" = 4277;
}
--

Event Metadata: com.apple.dt.IDERunOperationWorkerFinished : {
    "device_identifier" = "00006040-001251A40C7A801C";
    "device_model" = "Mac16,11";
    "device_osBuild" = "26.6.2 (25G83)";
    "device_osBuild_monotonic" = 2506008300;
    "device_os_variant" = 1;
    "device_platform" = "com.apple.platform.macosx";
    "device_platform_family" = 1;
    "device_reality" = 1;
    "device_thinningType" = "Mac16,11";
    "device_transport" = 4;
    "launchSession_schemeCommand" = Run;
    "launchSession_schemeCommand_enum" = 1;
    "launchSession_targetArch" = arm64;
    "launchSession_targetArch_enum" = 6;
    "operation_duration_ms" = 12;
    "operation_errorCode" = 20;
    "operation_errorDomain" = IDELaunchErrorDomain;
    "operation_errorWorker" = IDELaunchServicesLauncher;
    "operation_error_reportable" = 1;
    "operation_name" = IDERunOperationWorkerGroup;
    "param_consoleMode" = 1;
    "param_debugger_attachToExtensions" = 0;
    "param_debugger_attachToXPC" = 1;
    "param_debugger_type" = 3;
    "param_destination_isProxy" = 0;
    "param_destination_platform" = "com.apple.platform.macosx";
    "param_diag_MTE_enable" = 0;
    "param_diag_MainThreadChecker_stopOnIssue" = 0;
    "param_diag_MallocStackLogging_enableDuringAttach" = 0;
    "param_diag_MallocStackLogging_enableForXPC" = 1;
    "param_diag_allowLocationSimulation" = 1;
    "param_diag_checker_mtc_enable" = 1;
    "param_diag_checker_tpc_enable" = 1;
    "param_diag_gpu_frameCapture_enable" = 0;
    "param_diag_gpu_shaderValidation_enable" = 0;
    "param_diag_gpu_validation_enable" = 0;
    "param_diag_guardMalloc_enable" = 0;
    "param_diag_memoryGraphOnResourceException" = 0;
    "param_diag_queueDebugging_enable" = 1;
    "param_diag_runtimeProfile_generate" = 0;
    "param_diag_sanitizer_asan_enable" = 0;
    "param_diag_sanitizer_tsan_enable" = 0;
    "param_diag_sanitizer_tsan_stopOnIssue" = 0;
    "param_diag_sanitizer_ubsan_enable" = 0;
    "param_diag_sanitizer_ubsan_stopOnIssue" = 0;
    "param_diag_showNonLocalizedStrings" = 0;
    "param_diag_viewDebugging_enabled" = 1;
    "param_diag_viewDebugging_insertDylibOnLaunch" = 1;
    "param_install_style" = 2;
    "param_launcher_UID" = 2;
    "param_launcher_allowDeviceSensorReplayData" = 0;
    "param_launcher_kind" = 0;
    "param_launcher_style" = 99;
    "param_launcher_substyle" = 0;
    "param_lldbVersion_component_idx_1" = 0;
    "param_lldbVersion_monotonic" = 170302360020;
    "param_runnable_appExtensionHostRunMode" = 0;
    "param_runnable_productType" = "com.apple.product-type.application";
    "param_testing_launchedForTesting" = 0;
    "param_testing_suppressSimulatorApp" = 0;
    "param_testing_usingCLI" = 0;
    "sdk_canonicalName" = "macosx26.2";
    "sdk_osVersion" = "26.2";
    "sdk_platformID" = 6;
    "sdk_variant" = iosmac;
    "sdk_version_monotonic" = 2502005400;
}
--


System Information

macOS Version 26.6.2 (Build 25G83)
Xcode 26.2 (24549) (Build 17C48)
Timestamp: 2026-10-27T18:57:55+01:00

Hmmm, well, this time it seems cleaning the build folder and re-building from scratch did help. Weird, the previous time on the other computer it did not.

Perhaps it might have helped that this time before the re-build I went through my Accounts in the Xcode Settings to check whether all was OK. All was OK, nevertheless I wonder, might perhaps this, as a side-effect, re-set something somewhere related to the profile/signature/application identity weird and mysterious stuff, which caused the problem before?

Aside of this improbable (but I guess technically possible) hypothesis, I've absolutely no idea what the H. might be both the culprit before and the cure now :(

Anyway, touching wood the problem does not repeat and become worse... keep fingers crossed for me, thanks!