Data Call Error Handling
- Last UpdatedNov 18, 2025
- 6 minute read
- PI System
- AF SDK 2024 R2
- Developer
Error handling is an important aspect of writing software that can operate reliably. Because data access involves communicating with remote systems, performing data transformations, and calculations there are many possible problems that occur. These errors fall in several categories:
Invalid request: The method caller passed invalid arguments. Affects the entire method call.
Security: The method caller does not have permissions to execute the action. Affects the point or attribute.
Unsupported: The attribute does not support the requested method. Affects the attribute.
Configuration: The configuration of the data reference is invalid. Affects the attribute.
Communication: The data reference was unsuccessful communicating with its source. Affects all points/attributes using the source (e.g. all points from one PI Data Archive).
Calculation: The data reference encountered a problem computing the output from its input attributes. Affects the attribute.
Conversion: Unable to convert the value to conform to the type and UOM settings specified for the attribute. Affects the attribute.
In this topic, the approach to error handling of data calls in AF SDK is outlined.
Data read calls
Errors are returned from different read data calls in different ways. The goal is to present the error to the caller in a usable form while preserving partial results when possible. This section details handling for each call.
Wrapping errors
In some situations, there is an error that should be propagated to the caller but throwing an exception is not appropriate. For example, a data call on a list of attributes could encounter an error in retrieving data for one of the attributes. It would be unacceptable throw away all the data that was successfully retrieved so the error is wrapped in an AFValue and returned as the result for that attribute. The way the error is wrapped depends on the call type:
Single value (e.g. RecordedValue, InterpolatedValue): The error is set as the Value property of an AFValue. The value's Status property is set to AFValueStatusBad and the value's Attribute or PIPoint property is set to indicate what the error is associated with.
Multiple values (e.g. RecordedValues, InterpolatedValues): A value is created as in the single value case and that value returned as the only value in a AFValues collection.
Summary: A value is created as in the single value case and that value is set as the result of each requested summary type.
Summaries: A values collection is created as in the multiple values case and that collection is set as the result of each requested summary type.
Single PIPoint
PIPoint data access calls throw an exception if there is a point-level or server-level error. An OSIsoft.AF.AssetAFEnumerationValue containing a system state set will be used to indicate data errors returned from the PI Data Archive.
Single AFAttribute via AFData
Calls on an AFData instance will throw exceptions when the request is invalid (e.g. invalid arguments are passed or the call is unsupported). In other cases, the errors are wrapped as described above. Unlike direct calls on a PIPoint, an AFAttribute configured to use a PIPoint will wrap system-level or point-level errors.
PIPointList
PIPointList single value read calls (e.g. CurrentValue, RecordedValue, InterpolatedValue, etc.) produce a result in the form of a AFListResultsTKey, TResult, collection with PIPoint keys and OSIsoft.AF.AssetAFValue values. Errors (e.g. server-level or point-level) from this call are available directly from the Errors property or from the Results property wrapped in an OSIsoft.AF.AssetAFValue. The HasErrors property should be checked before accessing the Errors collection to avoid allocating an unnecessary collection.
AFListData single value read calls
AFListData single value read calls (e.g. CurrentValue, RecordedValue, InterpolatedValue, etc.) produce a result in the form of an IList<AFValue>. Any error is packaged in the OSIsoft.AF.AssetAFValue corresponding to the attribute in the list.
PIPointList and AFListData multiple values read calls
PIPointList and AFListData multiple value read calls (e.g. RecordedValues, InterpolatedValues, Summary, Summaries, etc.) produce a result in the form of IEnumerable<AFValues>, IEnumerable<IDictionary<AFSummaryTypes, AFValue>>, or IEnumerable<IDictionary<AFSummaryTypes, AFValues>>. Point or attribute level errors are wrapped as described above. A sever-level error will cause enumeration to throw an OperationCanceledException. The exception that triggered the cancellation will be set on the PIPagingConfigurationError property on the OSIsoft.AF.PIPIPagingConfiguration instance that was passed to the method.
Data write calls
As with read data calls, write data calls attempt to give the caller error feedback with context to understand what caused the problem.
AFData and PIPoint single value write calls
PIPoint and AFData single value write calls (e.g. UpdateValue) are void functions. An error (e.g. server-level, point-level, or event-level) in these calls will cause an exception to be thrown to the caller.
AFData, AFListData, PIPoint, and PIServer multiple values write calls
Errors (e.g. server-level, point-level, or event-level) for PIPoint , PIServer , AFData , and AFListData write methods that send multiple values (e.g. UpdateValues, ReplaceValues) are returned in the form of OSIsoft.AFAFErrorsTKey, where the key is OSIsoft.AF.AssetAFValue. If there is no error then null is returned.
AFData, AFListData, PIPoint, and PIServer ReplaceValues calls
Because ReplaceValues calls (i.e. replace data within a time range) can destroy data, validation of the call is very strict. AF SDK assumes that a bulk replace range call intends to replace all the data so if any data is invalid, the entire call fails. Thus, if the type conversion fails for one attribute in a bulk call, the error will be set on the offending attribute and all other attributes will report an error indicating they failed because another attribute failed.
When ReplaceValues is called on a PIPoint or PIServer, some conversions are delegated to the PI Data Archive (e.g. coercing string value to float). If the conversion fails in the PI Data Archive, the entire call will not be aborted. This behavior is similar to PIPoint UpdateValue, PIPoint and PIServer UpdateValues, as well as AFListData UpdateValues. Note that due to current limitations of PIBufSS, buffered writes might not return errors/results from PI Data Archive.
PIException errors that can be retried
When a data call throws a PIException or returns PIException errors, a retry may be successful depending on the type of exception.
Exceptions that might succeed when retried include:
PITimeoutException. This can be caused by a slow or unresponsive server that might be due to a server performance issue, a data call that requires heavy server resources (e.g. calculation), or a call that returns large amount of data. A retry might be successful if the server has become more responsive, e.g. has fewer clients/calls to serve. Note that alternatively, increasing OperationTimeOut property or breaking up the call into smaller chunks could improve the chances of success.
PIBufferException. This error can be produced when the buffer subsystem is unavailable or has a security issue. A retry with direct (non-buffered) write might be successful.
Exceptions that will not succeed on retry are errors that may be due to invalid PIPoint or invalid server configuration in the servers table entry, or that require an intervention (e.g. security/access change). Namely: