Skip to main content

Typed Getters, Defaults, and Error Codes

Every Quonfig SDK reads config through typed getters: getString, getBool, getInt and so on, spelled the way each language spells them. They all follow one contract. This page describes it once. Each SDK page has a short section with that SDK's method names and links back here.

The contract​

A typed getter returns a value of its type, or no value. It returns no value when:

  • the key is missing, or no rule matches;
  • the config holds another type. There is no string coercion: a stored string "false" is not a bool, "3" is not a number, and a duration config is not a string;
  • the value is malformed, for example an int config holding "twelve" or a duration config holding "30s";
  • the value comes from an environment variable that is not set, or it is a secret that cannot be decrypted (backend SDKs only; frontend SDKs never receive these values).

Numbers convert only when the result is exact. A float/double getter reads an int config (30 becomes 30.0). An int getter reads a double config only when it is a whole number within ±(2^53-1) (3.0 becomes 3). 3.9, 1e300 and 2^53 are type mismatches. Nothing is ever truncated.

With no value, you get your default. If you passed a default, the getter returns it, exactly as you passed it. If you didn't, the SDK's no-default policy decides (see the table below). On most backend SDKs the default policy is to throw, so a typed read with no default throws on a missing key, a wrong type or a malformed value.

Flag checks never throw. isEnabled (and its equivalent in each SDK) returns true only for a flag whose value is the bool true. It returns false for a missing key, a flag with no matching rule, a non-bool value (the string "true" included) and any resolution error, whatever the no-default policy is.

Each failure logs one warning per key. A type mismatch, a malformed value, an unset environment variable or a decryption failure logs one WARN per key per client. In most SDKs a flag check that returns false for a missing key or no matching rule logs one too. The warning names the key and the types, never the value.

Store each value with the config type you read it with. If a read keeps returning your default, the warning tells you which key to look at, and a details getter tells you why.

A broken config degrades to defaults​

Because a failed read returns your default, a wrong decryption key or an unset environment variable in production serves your code defaults and logs warnings. It doesn't stop your service. If a config must fail hard (a database password, say), read it without a default under a throwing no-default policy, or with the SDK's throwing variant (get*OrThrow in Java). That read then throws the underlying error.

Details getters and error codes​

The details getters (getStringDetails, get_int_details, GetBoolDetails and so on) return the value together with a reason, a variant and, when the read failed, an errorCode. Details getters never throw. A failed read has reason ERROR, your default (or no value) as the value, and one of these codes:

Error codeMeaningTypical cause
FLAG_NOT_FOUNDThe key is not in the loaded config.A typo, the wrong environment, or a config not sent to frontend SDKs.
TYPE_MISMATCHThe config holds another type than the one you asked for.Reading an int config with a string getter, or 3.9 with an int getter. A caller problem.
PARSE_ERRORThe value has the right type but does not parse.An int config holding "twelve", a duration holding "30s", or an environment variable that cannot be converted. A data problem.
PROVIDER_NOT_READYThe client has no config yet.A read before the first config loads, or while a client that started without config is still retrying.
GENERALAnything else.An unset environment variable, or a secret that cannot be decrypted.

Code that switches on the error code should handle all five. A few SDKs use a subset; see SDK differences.

Most SDKs also have an untyped details read (evaluateDetails or its equivalent). It returns any config's value in its stored form, for example a duration as its ISO 8601 text ("PT90S"), plus the stored type, with no type check. OpenFeature providers use it to return a duration's text.

The OpenFeature providers (Node, Web, Python, Ruby, Go, Java, .NET) wrap these SDKs, so they follow the same contract and report these codes as OpenFeature error codes. Each provider page lists its reason and error mapping.

Per-SDK reference​

SDKTyped gettersDefaultWith no defaultFlag checkDetails
NodegetString, getBool, getInt, getNumber, getStringList, getDuration (ms), getJSONoptional 3rd argument: (key, contexts?, default?)onNoDefault: "error" (default) throws; "warn" / "ignore" return undefinedisEnabledget*Details, evaluateDetails
Pythonget_string, get_bool, get_int, get_float, get_string_list, get_duration (seconds), get_jsondefault=on_no_default: "error" (default) raises; "warn" / "ignore" return Noneis_feature_enabled*_details, evaluate_details
Rubyget_string, get_bool, get_int, get_float, get_string_list, get_duration (ms), get_jsondefault:on_no_default: :raise (default) raises; :return_nil returns nilenabled?*_details, evaluate_details
GoGetStringValue, GetBoolValue, GetIntValue, GetFloatValue, GetStringSliceValue, GetDurationValue, GetJSONValuenone: each returns (value, ok, err); apply your default when ok is falseerr matches a sentinel such as quonfig.ErrTypeMismatchFeatureIsOnEvaluateDetails
JavagetString, getBool, getLong, getDouble, getStringList, getDuration, getJsonrequired argument (pass null for none)returns your default (or null); get*OrThrow throws insteadfeatureIsOnget*Details, evaluateDetails
.NETGetString, GetBool, GetInt, GetLong, GetDouble, GetStringList, GetDuration, GetJsonoptional defaultValue:OnNoDefault: Throw (default) throws; Warn / Ignore return nullIsFeatureEnabledGet*Details, EvaluateDetails
Swiftstring, int, double, stringList, duration (seconds), jsonrequired default: (json returns nil)not applicable; getters never throwisEnableddetails(_:), details(_:as:)
JavaScript, React, React Nativeget (any type, as stored) and getDurationgetDuration(key, default?)get returns undefined; never throwsisEnabledgetDetails

SDK differences​

  • Go has no default argument. Every getter returns (value, ok, err). When ok is false, apply your default; err matches quonfig.ErrNotFound (or is nil) for a missing key, quonfig.ErrTypeMismatch, quonfig.ErrUnableToCoerce (malformed), quonfig.ErrMissingEnvVar or quonfig.ErrUnableToDecrypt. FeatureIsOn returns (false, false) for anything that is not a bool true.
  • Java getters always take a default and never throw. Use get*OrThrow (for example getStringOrThrow) when a read must fail hard.
  • .NET has no PROVIDER_NOT_READY code. Before the first config loads, every key reads as missing (FlagNotFound), so your default or OnNoDefault applies.
  • Swift getters require a default and never throw. A malformed value reports TYPE_MISMATCH rather than PARSE_ERROR, and there is no GENERAL code.
  • Browser JavaScript, React and React Native receive values the server already evaluated, so there is no typed getter family beyond getDuration. get returns the value as stored, or undefined for a missing key or a value that doesn't match its declared type. These SDKs have no PROVIDER_NOT_READY code, and secrets and environment-variable values never reach them.