# Enum HomeError

java.lang.Object
java.lang.Enum<HomeError>
com.codename1.home.HomeError

All Implemented Interfaces:
  `Comparable<HomeError>`

public enum HomeError extends Enum<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 `Enum.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 Constant Summary

  Enum Constants
  Enum Constant
  Description
  `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.
  `AUTHORIZATION_REQUIRED`
  The user has not yet been asked.
  `BUSY`
  The platform refused because an operation of this kind is already in flight.
  `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.
  `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.
  `INVALID_DATA`
  A payload could not be decoded -- a malformed Matter setup payload, a platform value the port could not map onto a `TraitValue`.
  `NOT_CONFIGURED`
  The app is missing build configuration the backend needs -- an entitlement, a project id, an OAuth client.
  `NOT_SUPPORTED`
  The port, device or OS version has no smart-home support at all, or the requested capability is unavailable on this platform.
  `PIN_REJECTED`
  A door lock rejected the supplied PIN.
  `PIN_REQUIRED`
  A door lock refused the operation because it requires a PIN and none was supplied.
  `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.
  `RATE_LIMITED`
  The platform rate-limited the request.
  `READ_ONLY_TRAIT`
  The trait can be read but not written.
  `RESTRICTED`
  Smart-home access is blocked by parental controls or device management.
  `SIGN_IN_REQUIRED`
  No signed-in account.
  `TIMEOUT`
  The operation did not complete within its safety timeout.
  `TRAIT_NOT_SUPPORTED`
  The accessory does not expose this trait, or the backend cannot express it.
  `UNAUTHORIZED`
  The operation was refused for lack of authorization.
  `UNIT_MISMATCH`
  A `TraitUnit` was supplied that measures a different dimension than the trait requires.
  `UNKNOWN`
  Anything the port could not classify.
  `USER_CANCELED`
  The user dismissed a platform authorization, setup or commissioning flow.
  `VALUE_OUT_OF_RANGE`
  A write fell outside the range the accessory declares in its `TraitConstraint`.
  `WRITE_ONLY_TRAIT`
  The trait can be written but not read.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static HomeError`
  `forName(String name)`
  Resolves a constant by name, total: an unrecognized or `null` name answers `UNKNOWN` rather than throwing.
  `static HomeError`
  `valueOf(String name)`
  Returns the enum constant of this type with the specified name.
  `static HomeError[]`
  `values()`
  Returns an array containing the constants of this enum type, in the order they are declared.

  ### Methods inherited from class Enum

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

  ### Methods inherited from class Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### NOT_SUPPORTED

    public static final HomeError 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

    public static final HomeError 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

    public static final HomeError 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

    public static final HomeError 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

    public static final HomeError UNAUTHORIZED
    The operation was refused for lack of authorization.

  - ### AUTHORIZATION_REQUIRED

    public static final HomeError AUTHORIZATION_REQUIRED
    The user has not yet been asked. Recoverable by calling `SmartHome.requestAuthorization()`.

  - ### SIGN_IN_REQUIRED

    public static final HomeError 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

    public static final HomeError RESTRICTED
    Smart-home access is blocked by parental controls or device management. Not recoverable from inside the app.

  - ### USER_CANCELED

    public static final HomeError USER_CANCELED
    The user dismissed a platform authorization, setup or commissioning flow.

  - ### INVALID_ARGUMENT

    public static final HomeError 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

    public static final HomeError 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

    public static final HomeError UNIT_MISMATCH
    A `TraitUnit` was supplied that measures a different dimension than the trait requires.

  - ### READ_ONLY_TRAIT

    public static final HomeError READ_ONLY_TRAIT
    The trait can be read but not written.

  - ### WRITE_ONLY_TRAIT

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

  - ### PIN_REQUIRED

    public static final HomeError 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

    public static final HomeError PIN_REJECTED
    A door lock rejected the supplied PIN.

  - ### PROVIDER_UNAVAILABLE

    public static final HomeError PROVIDER_UNAVAILABLE
    The platform's smart-home provider is not installed -- Google Play services on Android. Recoverable via `SmartHome.openProviderSetup()`.

  - ### PROVIDER_UPDATE_REQUIRED

    public static final HomeError PROVIDER_UPDATE_REQUIRED
    The installed provider is too old. Also recoverable via `SmartHome.openProviderSetup()`.

  - ### NOT_CONFIGURED

    public static final HomeError 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

    public static final HomeError COMMISSIONING_FAILED
    Commissioning ran and did not add the accessory. The message carries the platform's own text.

  - ### COMMISSIONING_UNAVAILABLE

    public static final HomeError COMMISSIONING_UNAVAILABLE
    This platform cannot commission at all -- watchOS, tvOS, macOS, or an Android device with no Play services.

  - ### ECOSYSTEM_APP_MISSING

    public static final HomeError 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

    public static final HomeError RATE_LIMITED
    The platform rate-limited the request.

  - ### BUSY

    public static final HomeError BUSY
    The platform refused because an operation of this kind is already in flight. Retryable once it settles.

  - ### TIMEOUT

    public static final HomeError TIMEOUT
    The operation did not complete within its safety timeout.

  - ### INVALID_DATA

    public static final HomeError 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

    public static final HomeError UNKNOWN
    Anything the port could not classify. The message carries the platform's own text.

- ## Method Details

  - ### values

    public static HomeError[] values()
    Returns an array containing the constants of this enum type, in the order they are declared.
    Returns:
      an array containing the constants of this enum type, in the order they are declared

  - ### valueOf

    public static HomeError valueOf(String name)
    Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum type has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### 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`: the `Enum.name()` of a constant, or `null`

    ###### Returns

    the matching constant, or `UNKNOWN`