public enum HomeError

ImplementsComparable<HomeError>

Typed failure reasons carried by HomeException. Ports map their platform error codes onto these so cross-platform code can branch on a stable value instead of parsing messages.

Crossing the boundary by name, not by ordinal

The native bridges send the name() of one of these, not its ordinal, and forName(String) resolves it. Ordinals are a wire format that breaks silently: a port built against a build where a constant was inserted in the middle would map every error past the insertion point to the wrong one, and a mis-mapped UNAUTHORIZED looks exactly like a mis-mapped TIMEOUT to everyone downstream. Names cost a few bytes per failure – and a failure is not the hot path.

Enum constants

`NOT_SUPPORTED`	The port, device or OS version has no smart-home support at all, or the requested capability is unavailable on this platform.
`TRAIT_NOT_SUPPORTED`	The accessory does not expose this trait, or the backend cannot express it.
`ACCESSORY_NOT_FOUND`	No accessory with the supplied id is in the graph.
`ACCESSORY_UNREACHABLE`	The accessory is in the graph but the platform could not talk to it – unplugged, out of Thread range, or its bridge is offline.
`UNAUTHORIZED`	The operation was refused for lack of authorization.
`AUTHORIZATION_REQUIRED`	The user has not yet been asked.
`SIGN_IN_REQUIRED`	No signed-in account.
`RESTRICTED`	Smart-home access is blocked by parental controls or device management.
`USER_CANCELED`	The user dismissed a platform authorization, setup or commissioning flow.
`INVALID_ARGUMENT`	A request was rejected before reaching the platform because it was malformed – an empty write batch, a trait written with the wrong `TraitValueKind`, a negative timeout.
`VALUE_OUT_OF_RANGE`	A write fell outside the range the accessory declares in its `TraitConstraint`.
`UNIT_MISMATCH`	A `TraitUnit` was supplied that measures a different dimension than the trait requires.
`READ_ONLY_TRAIT`	The trait can be read but not written.
`WRITE_ONLY_TRAIT`	The trait can be written but not read.
`PIN_REQUIRED`	A door lock refused the operation because it requires a PIN and none was supplied.
`PIN_REJECTED`	A door lock rejected the supplied PIN.
`PROVIDER_UNAVAILABLE`	The platform’s smart-home provider is not installed – Google Play services on Android.
`PROVIDER_UPDATE_REQUIRED`	The installed provider is too old.
`NOT_CONFIGURED`	The app is missing build configuration the backend needs – an entitlement, a project id, an OAuth client.
`COMMISSIONING_FAILED`	Commissioning ran and did not add the accessory.
`COMMISSIONING_UNAVAILABLE`	This platform cannot commission at all – watchOS, tvOS, macOS, or an Android device with no Play services.
`ECOSYSTEM_APP_MISSING`	The ecosystem app a flow needs – Apple Home, Google Home – is not installed, so there was nothing to hand off to.
`RATE_LIMITED`	The platform rate-limited the request.
`BUSY`	The platform refused because an operation of this kind is already in flight.
`TIMEOUT`	The operation did not complete within its safety timeout.
`INVALID_DATA`	A payload could not be decoded – a malformed Matter setup payload, a platform value the port could not map onto a `TraitValue`.
`UNKNOWN`	Anything the port could not classify.

Methods

`public static` `HomeError[] values()`
`public static` `HomeError valueOf(String name)`
`public static` `HomeError forName(String name)`	Resolves a constant by name, total: an unrecognized or `null` name answers `UNKNOWN` rather than throwing.

Inherited methods

From Enum

clone, setEnumValues, getEnumValues, valueOf, equals, hashCode, toString, compareTo, name, ordinal, getDeclaringClass

From Object

getClass, notify, notifyAll, wait, wait, wait

Enum constant details

NOT_SUPPORTED

NOT_SUPPORTED

The port, device or OS version has no smart-home support at all, or the requested capability is unavailable on this platform. Returned by every operation on the fallback SmartHome base class.

TRAIT_NOT_SUPPORTED

TRAIT_NOT_SUPPORTED

The accessory does not expose this trait, or the backend cannot express it. Distinct from ACCESSORY_NOT_FOUND: the accessory is there and this particular capability is not.

Some traits can never succeed on a given backend rather than merely being absent from one accessory – Trait.OUTLET_IN_USE and Trait.TARGET_HUMIDITY have no Matter equivalent at all. The javadoc on each such constant says so.

ACCESSORY_NOT_FOUND

ACCESSORY_NOT_FOUND

No accessory with the supplied id is in the graph. Usually means the snapshot the caller is holding is stale; call SmartHome.refresh() and wait for it before reading SmartHome.getStructures() again.

ACCESSORY_UNREACHABLE

ACCESSORY_UNREACHABLE

The accessory is in the graph but the platform could not talk to it – unplugged, out of Thread range, or its bridge is offline. Retryable.

UNAUTHORIZED

UNAUTHORIZED

The operation was refused for lack of authorization.

AUTHORIZATION_REQUIRED

AUTHORIZATION_REQUIRED

The user has not yet been asked. Recoverable by calling SmartHome.requestAuthorization().

SIGN_IN_REQUIRED

SIGN_IN_REQUIRED

No signed-in account. Google Home only: the Home APIs need an account and a per-structure grant before any accessory is visible.

RESTRICTED

RESTRICTED

Smart-home access is blocked by parental controls or device management. Not recoverable from inside the app.

USER_CANCELED

USER_CANCELED

The user dismissed a platform authorization, setup or commissioning flow.

INVALID_ARGUMENT

INVALID_ARGUMENT

A request was rejected before reaching the platform because it was malformed – an empty write batch, a trait written with the wrong TraitValueKind, a negative timeout.

VALUE_OUT_OF_RANGE

VALUE_OUT_OF_RANGE

A write fell outside the range the accessory declares in its TraitConstraint.

Deliberately an error rather than a clamp. An app that asked for 40 degrees and silently got 38 never learns it was wrong, and the bug surfaces as a user complaint about a thermostat rather than as a failure at the call site.

UNIT_MISMATCH

UNIT_MISMATCH

A TraitUnit was supplied that measures a different dimension than the trait requires.

READ_ONLY_TRAIT

READ_ONLY_TRAIT

The trait can be read but not written.

WRITE_ONLY_TRAIT

WRITE_ONLY_TRAIT

The trait can be written but not read. Rare; some Matter attributes are write-only commands in disguise.

PIN_REQUIRED

PIN_REQUIRED

A door lock refused the operation because it requires a PIN and none was supplied. Set one with TraitWrite.setAuthorizationData(java.lang.String).

Matter locks with RequirePINforRemoteOperation set behave this way. HomeKit never takes a PIN.

PIN_REJECTED

PIN_REJECTED

A door lock rejected the supplied PIN.

PROVIDER_UNAVAILABLE

PROVIDER_UNAVAILABLE

The platform’s smart-home provider is not installed – Google Play services on Android. Recoverable via SmartHome.openProviderSetup().

PROVIDER_UPDATE_REQUIRED

PROVIDER_UPDATE_REQUIRED

The installed provider is too old. Also recoverable via SmartHome.openProviderSetup().

NOT_CONFIGURED

NOT_CONFIGURED

The app is missing build configuration the backend needs – an entitlement, a project id, an OAuth client. Always accompanied by HomeConfigurationException and by text from SmartHome.getConfigurationProblems() naming what is missing.

COMMISSIONING_FAILED

COMMISSIONING_FAILED

Commissioning ran and did not add the accessory. The message carries the platform’s own text.

COMMISSIONING_UNAVAILABLE

COMMISSIONING_UNAVAILABLE

This platform cannot commission at all – watchOS, tvOS, macOS, or an Android device with no Play services.

ECOSYSTEM_APP_MISSING

ECOSYSTEM_APP_MISSING

The ecosystem app a flow needs – Apple Home, Google Home – is not installed, so there was nothing to hand off to.

RATE_LIMITED

RATE_LIMITED

The platform rate-limited the request.

BUSY

BUSY

The platform refused because an operation of this kind is already in flight. Retryable once it settles.

TIMEOUT

TIMEOUT

The operation did not complete within its safety timeout.

INVALID_DATA

INVALID_DATA

A payload could not be decoded – a malformed Matter setup payload, a platform value the port could not map onto a TraitValue. Never surfaces as an unchecked exception from a parser.

UNKNOWN

UNKNOWN

Anything the port could not classify. The message carries the platform’s own text.

Method details

values

public static HomeError[] values()

valueOf

public static HomeError valueOf(String name)

forName

public static HomeError forName(String name)

Resolves a constant by name, total: an unrecognized or null name answers UNKNOWN rather than throwing.

This exists so the boundary cannot throw. Enum.valueOf raises IllegalArgumentException on an unknown name, and the one place this is called is while decoding a failure that has already happened – so the throw would replace a real error the caller could act on with an unrelated one they cannot. A port from a newer build naming an error this one does not have degrades to UNKNOWN with the platform text intact.

Parameters

name String: the name() of a constant, or null

Returns

the matching constant, or UNKNOWN